\input texinfo @c -*-texinfo-*-
@c %**start of header
+
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c o
@c GNAT DOCUMENTATION o
@c o
@c G N A T _ U G N o
@c o
-@c Copyright (C) 1992-2007, AdaCore o
-@c o
-@c GNAT is free software; you can redistribute it and/or modify it under o
-@c terms of the GNU General Public License as published by the Free Soft- o
-@c ware Foundation; either version 2, or (at your option) any later ver- o
-@c sion. GNAT is distributed in the hope that it will be useful, but WITH- o
-@c OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY o
-@c or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License o
-@c for more details. You should have received a copy of the GNU General o
-@c Public License distributed with GNAT; see file COPYING. If not, write o
-@c to the Free Software Foundation, 51 Franklin Street, Fifth Floor, o
-@c Boston, MA 02110-1301, USA. o
+@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
@c o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
+@setfilename gnat_ugn.info
+
+@copying
+Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation,
+Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end copying
+
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c
@c GNAT_UGN Style Guide
@c
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
-@setfilename gnat_ugn.info
-
@set NOW January 2007
@c This flag is used where the text refers to conditions that exist when the
@c text was entered into the document but which may change over time.
@set EDITION GNAT
@set DEFAULTLANGUAGEVERSION Ada 2005
@set NONDEFAULTLANGUAGEVERSION Ada 95
-@set FILE gnat_ugn
@ifset unw
@set PLATFORM
@set PLATFORM OpenVMS
@end ifset
+@c @ovar(ARG)
+@c ----------
+@c The ARG is an optional argument. To be used for macro arguments in
+@c their documentation (@defmac).
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}@c
+@end macro
+
@settitle @value{EDITION} User's Guide @value{PLATFORM}
@dircategory GNU Ada tools
@direntry
-* @value{EDITION} User's Guide (@value{FILE}) @value{PLATFORM}
+* @value{EDITION} User's Guide (gnat_ugn) @value{PLATFORM}
@end direntry
@include gcc-common.texi
@syncodeindex fn cp
@c %**end of header
-@copying
-Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation,
-Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being ``GNU Free Documentation License'', with the
-Front-Cover Texts being
-``@value{EDITION} User's Guide'',
-and with no Back-Cover Texts.
-A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-@end copying
-
@titlepage
@title @value{EDITION} User's Guide
@ifset vms
* 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
Improving Performance
* Performance Considerations::
+* Text_IO Suggestions::
* Reducing Size of Ada Executables with gnatelim::
* Reducing Size of Executables with unused subprogram/data elimination::
* Examples of gnatkr Usage::
Preprocessing Using gnatprep
+* Preprocessing Symbols::
* Using gnatprep::
* Switches for gnatprep::
* Form of Definitions File::
* The External Symbol Naming Scheme of GNAT::
* Converting Ada Files to html with gnathtml::
+@ifclear vms
+Code Coverage and Profiling
+
+* Code Coverage of Ada Programs using gcov::
+* Profiling an Ada Program using gprof::
+@end ifclear
+
Running and Debugging Ada Programs
* The GNAT Debugger GDB::
* Solaris-Specific Considerations::
* Linux-Specific Considerations::
* AIX-Specific Considerations::
+* Irix-Specific Considerations::
Example of Binder Output File
@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.
@emph{Emphasis}.
@item
-[optional information or parameters]
+@r{[}optional information or parameters@r{]}
@item
Examples are described by text
@smallexample @c ada
pragma Source_File_Name (
Spec_File_Name => FILE_NAME_PATTERN
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ @r{[},Casing => CASING_SPEC@r{]}
+ @r{[},Dot_Replacement => STRING_LITERAL@r{]});
pragma Source_File_Name (
Body_File_Name => FILE_NAME_PATTERN
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ @r{[},Casing => CASING_SPEC@r{]}
+ @r{[},Dot_Replacement => STRING_LITERAL@r{]});
pragma Source_File_Name (
Subunit_File_Name => FILE_NAME_PATTERN
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ @r{[},Casing => CASING_SPEC@r{]}
+ @r{[},Dot_Replacement => STRING_LITERAL@r{]});
FILE_NAME_PATTERN ::= STRING_LITERAL
CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
it is necessary to compile in optimizing mode.
@cindex @option{-gnatN} switch
-The use of @option{-gnatN} activates a more extensive inlining optimization
+The use of @option{-gnatN} activates inlining optimization
that is performed by the front end of the compiler. This inlining does
not require that the code generation be optimized. Like @option{-gnatn},
the use of this switch generates additional dependencies.
@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary
to specify both options.
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
+
@item
If an object file @file{O} depends on the proper body of a subunit through
inlining or instantiation, it depends on the parent unit of the subunit.
Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram,
this means that the body of the subprogram is provided by the compiler itself,
usually by means of an efficient code sequence, and that the user does not
-supply an explicit body for it. In an application program, the pragma can
-only be applied to the following two sets of names, which the GNAT compiler
-recognizes.
+supply an explicit body for it. In an application program, the pragma may
+be applied to the following sets of names:
@itemize @bullet
@item
modulus, and the second parameter must be of type Natural.
The return type must be the same as the type of the first argument. The size
of this type can only be 8, 16, 32, or 64.
-@item binary arithmetic operators: ``+'', ``-'', ``*'', ``/''
+
+@item
+Binary arithmetic operators: ``+'', ``-'', ``*'', ``/''
The corresponding operator declaration must have parameters and result type
that have the same root numeric type (for example, all three are long_float
types). This simplifies the definition of operations that use type checking
explicit body. The pragma makes it simpler to introduce such declarations.
It incurs no overhead in compilation time or code size, because it is
implemented as a single machine instruction.
+
+@item
+General subprogram entities, to bind an Ada subprogram declaration to
+a compiler builtin by name with back-ends where such interfaces are
+available. A typical example is the set of ``__builtin'' functions
+exposed by the GCC back-end, as in the following example:
+
+@smallexample @c ada
+ function builtin_sqrt (F : Float) return Float;
+ pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf");
+@end smallexample
+
+Most of the GCC builtins are accessible this way, and as for other
+import conventions (e.g. C), it is the user's responsibility to ensure
+that the Ada subprogram profile matches the underlying builtin
+expectations.
@end itemize
+
@noindent
@ifset unw
The basic command for compiling a file containing an Ada unit is
@smallexample
-$ gcc -c [@var{switches}] @file{file name}
+$ gcc -c @ovar{switches} @file{file name}
@end smallexample
@noindent
are ignored, and @option{-gnatn} and @option{-gnatN} have no
effect if this switch is present.
+@item -fno-inline-functions
+@cindex @option{-fno-inline-functions} (@command{gcc})
+Suppresses automatic inlining of small subprograms, which is enabled
+if @option{-O3} is used.
+
+@item -fno-inline-functions-called-once
+@cindex @option{-fno-inline-functions-called-once} (@command{gcc})
+Suppresses inlining of subprograms local to the unit and called once
+from within it, which is enabled if @option{-O1} is used.
+
@item -fno-strict-aliasing
@cindex @option{-fno-strict-aliasing} (@command{gcc})
Causes the compiler to avoid assumptions regarding non-aliasing
Makes the compiler output stack usage information for the program, on a
per-function basis. See @ref{Static Stack Usage Analysis} for details.
-@item -fcallgraph-info[=su]
+@item -fcallgraph-info@r{[}=su@r{]}
@cindex @option{-fcallgraph-info} (@command{gcc})
Makes the compiler output callgraph information for the program, on a
per-file basis. The information is generated in the VCG format. It can
Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
activated. Note that these pragmas can also be controlled using the
configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}.
+It also activates pragmas @code{Check}, @code{Precondition}, and
+@code{Postcondition}. Note that these pragmas can also be controlled
+using the configuration pragma @code{Check_Policy}.
@item -gnatA
@cindex @option{-gnatA} (@command{gcc})
@end ifclear
(@pxref{The Configuration Pragmas Files}).
-@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
+@item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=@var{value}@r{]}
@cindex @option{-gnateD} (@command{gcc})
-Defines a symbol, associated with value, for preprocessing.
+Defines a symbol, associated with @var{value}, for preprocessing.
(@pxref{Integrated Preprocessing}).
@item -gnatef
@item -gnatq
@cindex @option{-gnatq} (@command{gcc})
-Don't quit; try semantics, even if parse errors.
+Don't quit. Try semantics, even if parse errors.
@item -gnatQ
@cindex @option{-gnatQ} (@command{gcc})
-Don't quit; generate @file{ALI} and tree files even if illegalities.
+Don't quit. Generate @file{ALI} and tree files even if illegalities.
+
+@item -gnatr
+@cindex @option{-gnatr} (@command{gcc})
+Treat pragma Restrictions as Restriction_Warnings.
-@item ^-gnatR[0/1/2/3[s]]^/REPRESENTATION_INFO^
+@item ^-gnatR@r{[}0@r{/}1@r{/}2@r{/}3@r{[}s@r{]]}^/REPRESENTATION_INFO^
@cindex @option{-gnatR} (@command{gcc})
Output representation information for declared types and objects.
Control level of validity checking. See separate section describing
this feature.
-@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}[,@dots{}])^
+@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}@r{[},@dots{}@r{]})^
@cindex @option{^-gnatw^/WARNINGS^} (@command{gcc})
Warning mode where
^@var{xxx} is a string of option letters that^the list of options^ denotes
Library (RTL) ALI files.
@ifclear vms
-@item -O[@var{n}]
+@item -O@ovar{n}
@cindex @option{-O} (@command{gcc})
@var{n} controls the optimization level.
This is the default behavior in the absence of an @option{/OPTIMIZE}
qualifier.
-@item /OPTIMIZE[=(keyword[,@dots{}])]
+@item /OPTIMIZE@r{[}=(keyword@r{[},@dots{}@r{]})@r{]}
@cindex @option{/OPTIMIZE} (@code{GNAT COMPILE})
Selects the level of optimization for your program. The supported
keywords are as follows:
Turn off warnings generated by the back end of the compiler. Use of
this switch also causes the default for front end warnings to be set
to suppress (as though @option{-gnatws} had appeared at the start of
-the options.
+the options).
@end table
This switch suppresses warnings for static fixed-point expressions whose
value is not an exact multiple of Small.
+@item -gnatw.b
+@emph{Activate warnings on biased representation.}
+@cindex @option{-gnatw.b} (@command{gcc})
+@cindex Biased representation
+This switch activates warnings when a size clause, value size clause, component
+clause, or component size clause forces the use of biased representation for an
+integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
+to represent 10/11). The default is that such warnings are generated.
+
+@item -gnatw.B
+@emph{Suppress warnings on biased representation.}
+@cindex @option{-gnatwB} (@command{gcc})
+This switch suppresses warnings for representation clauses that force the use
+of biased representation.
+
@item -gnatwc
@emph{Activate warnings on conditionals.}
@cindex @option{-gnatwc} (@command{gcc})
The warning string still appears, but the warning messages are counted
as errors, and prevent the generation of an object file.
+@item -gnatw.e
+@emph{Activate every optional warning}
+@cindex @option{-gnatw.e} (@command{gcc})
+@cindex Warnings, activate every optional warning
+This switch activates all optional warnings, including those which
+are not activated by @code{-gnatwa}.
+
@item -gnatwf
@emph{Activate warnings on unreferenced formals.}
@cindex @option{-gnatwf} (@command{gcc})
This switch disables warnings on variables that could be declared constants.
@item -gnatwl
-@emph{Activate warnings for missing elaboration pragmas.}
+@emph{Activate warnings for elaboration pragmas.}
@cindex @option{-gnatwl} (@command{gcc})
@cindex Elaboration, warnings
This switch activates warnings on missing
@code{Elaborate_All} and @code{Elaborate} pragmas.
See the section in this guide on elaboration checking for details on
-when such pragmas should be used. Warnings are also generated if you
+when such pragmas should be used. In dynamic elaboration mode, this switch
+generations warnings about the need to add elaboration pragmas. Note however,
+that if you blindly follow these warnings, and add @code{Elaborate_All}
+warnings wherever they are recommended, you basically end up with the
+equivalent of the static elaboration model, which may not be what you want for
+legacy code for which the static model does not work.
+
+For the static model, the messages generated are labeled "info:" (for
+information messages). They are not warnings to add elaboration pragmas,
+merely informational messages showing what implicit elaboration pragmas
+have been added, for use in analyzing elaboration circularity problems.
+
+Warnings are also generated if you
are using the static mode of elaboration, and a @code{pragma Elaborate}
is encountered. The default is that such warnings
are not generated.
This warning is not automatically turned on by the use of @option{-gnatwa}.
@item -gnatwL
-@emph{Suppress warnings for missing elaboration pragmas.}
+@emph{Suppress warnings for elaboration pragmas.}
@cindex @option{-gnatwL} (@command{gcc})
This switch suppresses warnings on missing Elaborate and Elaborate_All pragmas.
See the section in this guide on elaboration checking for details on
inlining mechanism cannot inline a call, it will simply ignore the
request silently.
+@item -gnatw.p
+@emph{Activate warnings on parameter ordering.}
+@cindex @option{-gnatw.p} (@command{gcc})
+@cindex Parameter order, warnings
+This switch activates warnings for cases of suspicious parameter
+ordering when the list of arguments are all simple identifiers that
+match the names of the formals, but are in a different order. The
+warning is suppressed if any use of named parameter notation is used,
+so this is the appropriate way to suppress a false positive (and
+serves to emphasize that the "misordering" is deliberate). The
+default is
+that such warnings are not given.
+This warning can also be turned on using @option{-gnatwa}.
+
+@item -gnatw.P
+@emph{Suppress warnings on parameter ordering.}
+@cindex @option{-gnatw.P} (@command{gcc})
+This switch suppresses warnings on cases of suspicious parameter
+ordering.
+
@item -gnatwq
@emph{Activate warnings on questionable missing parentheses.}
@cindex @option{-gnatwq} (@command{gcc})
@item -gnatwW
@emph{Suppress warnings on wrong low bound assumption.}
@cindex @option{-gnatwW} (@command{gcc})
-This switch activates warnings for indexing an unconstrained string parameter
-with a literal or S'Length. This warning can also be suppressed by providing
-an Assert pragma that checks the low bound, for example:
+This switch suppresses warnings for indexing an unconstrained string parameter
+with a literal or S'Length. Note that this warning can also be suppressed
+in a particular case by adding an
+assertion that the lower bound is 1,
+as shown in the following example.
@smallexample @c ada
procedure K (S : String) is
@dots{}
@end smallexample
+@item -gnatw.w
+@emph{Activate warnings on unnecessary Warnings Off pragmas}
+@cindex @option{-gnatw.w} (@command{gcc})
+@cindex Warnings Off control
+This switch activates warnings for use of @code{pragma Warnings (Off, entity}
+where either the pragma is entirely useless (because it suppresses no
+warnings), or it could be replaced by @code{pragma Unreferenced} or
+@code{pragma Unmodified}.The default is that these warnings are not given.
+Note that this warning is not included in -gnatwa, it must be
+activated explicitly.
+
+@item -gnatw.W
+@emph{Suppress warnings on unnecessary Warnings Off pragmas}
+@cindex @option{-gnatw.W} (@command{gcc})
+This switch suppresses warnings for use of @code{pragma Warnings (Off, entity}.
+
@item -gnatwx
@emph{Activate warnings on Export/Import pragmas.}
@cindex @option{-gnatwx} (@command{gcc})
This switch activates warnings for unchecked conversions
where the types are known at compile time to have different
sizes. The default
-is that such warnings are generated.
+is that such warnings are generated. Warnings are also
+generated for subprogram pointers with different conventions,
+and, on VMS only, for data pointers with different conventions.
This warning can also be turned on using @option{-gnatwa}.
@item -gnatwZ
@cindex @option{-gnatwZ} (@command{gcc})
This switch suppresses warnings for unchecked conversions
where the types are known at compile time to have different
-sizes.
+sizes or conventions.
+
+@item ^-Wunused^WARNINGS=UNUSED^
+@cindex @option{-Wunused}
+The warnings controlled by the @option{-gnatw} switch are generated by
+the front end of the compiler. The @option{GCC} back end can provide
+additional warnings and they are controlled by the @option{-W} switch.
+For example, @option{^-Wunused^WARNINGS=UNUSED^} activates back end
+warnings for entities that are declared but not referenced.
@item ^-Wuninitialized^WARNINGS=UNINITIALIZED^
@cindex @option{-Wuninitialized}
-The warnings controlled by the @option{-gnatw} switch are generated by the
-front end of the compiler. In some cases, the @option{^gcc^GCC^} back end
-can provide additional warnings. One such useful warning is provided by
-@option{^-Wuninitialized^WARNINGS=UNINITIALIZED^}. This must be used in
-conjunction with turning on optimization mode. This causes the flow
-analysis circuits of the back end optimizer to output additional
-warnings about uninitialized variables.
+Similarly, @option{^-Wuninitialized^WARNINGS=UNINITIALIZED^} activates
+the back end warning for uninitialized variables. This switch must be
+used in conjunction with an optimization level greater than zero.
+
+@item ^-Wall^/ALL_BACK_END_WARNINGS^
+@cindex @option{-Wall}
+This switch enables all the above warnings from the @option{GCC} back end.
+The code generator detects a number of warning situations that are missed
+by the @option{GNAT} front end, and this switch can be used to activate them.
+The use of this switch also sets the default front end warning mode to
+@option{-gnatwa}, that is, most front end warnings activated as well.
@item ^-w^/NO_BACK_END_WARNINGS^
@cindex @option{-w}
-This switch suppresses warnings from the @option{^gcc^GCC^} back end. The
-code generator detects a number of warning situations that are missed
-by the @option{GNAT} front end, and this switch can be used to suppress them.
+Conversely, this switch suppresses warnings from the @option{GCC} back end.
The use of this switch also sets the default front end warning mode to
@option{-gnatws}, that is, front end warnings suppressed as well.
@smallexample
@cartouche
- @b{pragma} Assert (@var{Boolean-expression} [,
- @var{static-string-expression}])
+ @b{pragma} Assert (@var{Boolean-expression} @r{[},
+ @var{static-string-expression}@r{]})
@b{pragma} Debug (@var{procedure call})
@end cartouche
@end smallexample
debugging procedures to be called between declarations.
@ifset vms
-@item /DEBUG[=debug-level]
+@item /DEBUG@r{[}=debug-level@r{]}
@itemx /NODEBUG
Specifies how much debugging information is to be included in
the resulting object file where 'debug-level' is one of the following:
checking of @code{@b{in out}} procedure arguments.
The specification of additional validity checking generates extra code (and
-in the case of @option{-gnatVa} the code expansion can be substantial.
+in the case of @option{-gnatVa} the code expansion can be substantial).
However, these additional checks can be very useful in detecting
uninitialized variables, incorrect use of unchecked conversion, and other
errors leading to invalid values. The use of pragma @code{Initialize_Scalars}
@table @option
@c !sort!
-@item 1-9
+@item 0-9
@emph{Specify indentation level.}
If a digit from 1-9 appears
^in the string after @option{-gnaty}^as an option for /STYLE_CHECKS^
then proper indentation is checked, with the digit indicating the
-indentation level required.
+indentation level required. A value of zero turns off this style check.
The general style of required indentation is as specified by
the examples in the Ada Reference Manual. Full line comments must be
aligned with the @code{--} starting on a column that is a multiple of
@item ^a^ATTRIBUTE^
@emph{Check attribute casing.}
-If the ^letter a^word ATTRIBUTE^ appears in the string after @option{-gnaty}
-then attribute names, including the case of keywords such as @code{digits}
+Attribute names, including the case of keywords such as @code{digits}
used as attributes names, must be written in mixed case, that is, the
initial letter and any letter following an underscore must be uppercase.
All other letters must be lowercase.
@item ^A^ARRAY_INDEXES^
@emph{Use of array index numbers in array attributes.}
-If the ^letter A^word ARRAY_INDEXES^ appears in the string after
-@option{-gnaty} then when using the array attributes First, Last, Range,
+When using the array attributes First, Last, Range,
or Length, the index number must be omitted for one-dimensional arrays
and is required for multi-dimensional arrays.
@item ^b^BLANKS^
@emph{Blanks not allowed at statement end.}
-If the ^letter b^word BLANKS^ appears in the string after @option{-gnaty} then
-trailing blanks are not allowed at the end of statements. The purpose of this
+Trailing blanks are not allowed at the end of statements. The purpose of this
rule, together with h (no horizontal tabs), is to enforce a canonical format
for the use of blanks to separate source tokens.
@item ^c^COMMENTS^
@emph{Check comments.}
-If the ^letter c^word COMMENTS^ appears in the string after @option{-gnaty}
-then comments must meet the following set of rules:
+Comments must meet the following set of rules:
@itemize @bullet
@item ^d^DOS_LINE_ENDINGS^
@emph{Check no DOS line terminators present.}
-If the ^letter d^word DOS_LINE_ENDINGS^ appears in the string after
-@option{-gnaty} then all lines must be terminated by a single ASCII.LF
+All lines must be terminated by a single ASCII.LF
character (in particular the DOS line terminator sequence CR/LF is not
allowed).
@item ^e^END^
@emph{Check end/exit labels.}
-If the ^letter e^word END^ appears in the string after @option{-gnaty} then
-optional labels on @code{end} statements ending subprograms and on
+Optional labels on @code{end} statements ending subprograms and on
@code{exit} statements exiting named loops, are required to be present.
@item ^f^VTABS^
@emph{No form feeds or vertical tabs.}
-If the ^letter f^word VTABS^ appears in the string after @option{-gnaty} then
-neither form feeds nor vertical tab characters are permitted
+Neither form feeds nor vertical tab characters are permitted
in the source text.
@item ^g^GNAT^
@emph{GNAT style mode}
-If the ^letter g^word GNAT^ appears in the string after @option{-gnaty} then
-the set of style check switches is set to match that used by the GNAT sources.
+The set of style check switches is set to match that used by the GNAT sources.
This may be useful when developing code that is eventually intended to be
incorporated into GNAT. For further details, see GNAT sources.
@item ^h^HTABS^
@emph{No horizontal tabs.}
-If the ^letter h^word HTABS^ appears in the string after @option{-gnaty} then
-horizontal tab characters are not permitted in the source text.
+Horizontal tab characters are not permitted in the source text.
Together with the b (no blanks at end of line) check, this
enforces a canonical form for the use of blanks to separate
source tokens.
@item ^i^IF_THEN^
@emph{Check if-then layout.}
-If the ^letter i^word IF_THEN^ appears in the string after @option{-gnaty},
-then the keyword @code{then} must appear either on the same
+The keyword @code{then} must appear either on the same
line as corresponding @code{if}, or on a line on its own, lined
up under the @code{if} with at least one non-blank line in between
containing all or part of the condition to be tested.
@item ^I^IN_MODE^
@emph{check mode IN keywords}
-If the ^letter I (upper case)^word IN_MODE^ appears in the string
-after @option{-gnaty} then mode @code{in} (the default mode) is not
+Mode @code{in} (the default mode) is not
allowed to be given explicitly. @code{in out} is fine,
but not @code{in} on its own.
@item ^k^KEYWORD^
@emph{Check keyword casing.}
-If the ^letter k^word KEYWORD^ appears in the string after @option{-gnaty} then
-all keywords must be in lower case (with the exception of keywords
+All keywords must be in lower case (with the exception of keywords
such as @code{digits} used as attribute names to which this check
does not apply).
@item ^l^LAYOUT^
@emph{Check layout.}
-If the ^letter l^word LAYOUT^ appears in the string after @option{-gnaty} then
-layout of statement and declaration constructs must follow the
+Layout of statement and declaration constructs must follow the
recommendations in the Ada Reference Manual, as indicated by the
form of the syntax rules. For example an @code{else} keyword must
be lined up with the corresponding @code{if} keyword.
@item ^Lnnn^MAX_NESTING=nnn^
@emph{Set maximum nesting level}
-If the sequence ^Lnnn^MAX_NESTING=nnn^, where nnn is a decimal number in
-the range 0-999, appears in the string after @option{-gnaty} then the
-maximum level of nesting of constructs (including subprograms, loops,
-blocks, packages, and conditionals) may not exceed the given value. A
-value of zero disconnects this style check.
+The maximum level of nesting of constructs (including subprograms, loops,
+blocks, packages, and conditionals) may not exceed the given value
+@option{nnn}. A value of zero disconnects this style check.
@item ^m^LINE_LENGTH^
@emph{Check maximum line length.}
-If the ^letter m^word LINE_LENGTH^ appears in the string after @option{-gnaty}
-then the length of source lines must not exceed 79 characters, including
+The length of source lines must not exceed 79 characters, including
any trailing blanks. The value of 79 allows convenient display on an
80 character wide device or window, allowing for possible special
treatment of 80 character lines. Note that this count is of
@item ^Mnnn^MAX_LENGTH=nnn^
@emph{Set maximum line length.}
-If the sequence ^M^MAX_LENGTH=^nnn, where nnn is a decimal number, appears in
-the string after @option{-gnaty} then the length of lines must not exceed the
-given value. The maximum value that can be specified is 32767.
+The length of lines must not exceed the
+given value @option{nnn}. The maximum value that can be specified is 32767.
@item ^n^STANDARD_CASING^
@emph{Check casing of entities in Standard.}
-If the ^letter n^word STANDARD_CASING^ appears in the string
-after @option{-gnaty} then any identifier from Standard must be cased
+Any identifier from Standard must be cased
to match the presentation in the Ada Reference Manual (for example,
@code{Integer} and @code{ASCII.NUL}).
+@item ^N^NONE^
+@emph{Turn off all style checks}
+All style check options are turned off.
+
@item ^o^ORDERED_SUBPROGRAMS^
@emph{Check order of subprogram bodies.}
-If the ^letter o^word ORDERED_SUBPROGRAMS^ appears in the string
-after @option{-gnaty} then all subprogram bodies in a given scope
+All subprogram bodies in a given scope
(e.g.@: a package body) must be in alphabetical order. The ordering
rule uses normal Ada rules for comparing strings, ignoring casing
of letters, except that if there is a trailing numeric suffix, then
@item ^p^PRAGMA^
@emph{Check pragma casing.}
-If the ^letter p^word PRAGMA^ appears in the string after @option{-gnaty} then
-pragma names must be written in mixed case, that is, the
+Pragma names must be written in mixed case, that is, the
initial letter and any letter following an underscore must be uppercase.
All other letters must be lowercase.
@item ^r^REFERENCES^
@emph{Check references.}
-If the ^letter r^word REFERENCES^ appears in the string after @option{-gnaty}
-then all identifier references must be cased in the same way as the
+All identifier references must be cased in the same way as the
corresponding declaration. No specific casing style is imposed on
identifiers. The only requirement is for consistency of references
with declarations.
@item ^S^STATEMENTS_AFTER_THEN_ELSE^
@emph{Check no statements after THEN/ELSE.}
-If the ^letter S^word STATEMENTS_AFTER_THEN_ELSE^ appears in the
-string after @option{-gnaty} then it is not permitted to write any
-statements on the same line as a THEN OR ELSE keyword following the
+No statements are allowed
+on the same line as a THEN or ELSE keyword following the
keyword in an IF statement. OR ELSE and AND THEN are not affected,
and a special exception allows a pragma to appear after ELSE.
@item ^s^SPECS^
@emph{Check separate specs.}
-If the ^letter s^word SPECS^ appears in the string after @option{-gnaty} then
-separate declarations (``specs'') are required for subprograms (a
+Separate declarations (``specs'') are required for subprograms (a
body is not allowed to serve as its own declaration). The only
exception is that parameterless library level procedures are
not required to have a separate declaration. This exception covers
@item ^t^TOKEN^
@emph{Check token spacing.}
-If the ^letter t^word TOKEN^ appears in the string after @option{-gnaty} then
-the following token spacing rules are enforced:
+The following token spacing rules are enforced:
@itemize @bullet
@item ^u^UNNECESSARY_BLANK_LINES^
@emph{Check unnecessary blank lines.}
-Check for unnecessary blank lines. A blank line is considered
+Unnecessary blank lines are not allowed. A blank line is considered
unnecessary if it appears at the end of the file, or if more than
one blank line occurs in sequence.
@item ^x^XTRA_PARENS^
@emph{Check extra parentheses.}
-Check for the use of an unnecessary extra level of parentheses (C-style)
+Unnecessary extra level of parentheses (C-style) are not allowed
around conditions in @code{if} statements, @code{while} statements and
@code{exit} statements.
+@item ^y^ALL_BUILTIN^
+@emph{Set all standard style check options}
+This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
+options enabled with the exception of @option{-gnatyo}, @option{-gnatyI},
+@option{-gnatyS}, @option{-gnatyLnnn},
+@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
+
+@ifclear vms
+@item -
+@emph{Remove style check options}
+This causes any subsequent options in the string to act as canceling the
+corresponding style check option. To cancel maximum nesting level control,
+use @option{L} parameter witout any integer value after that, because any
+digit following @option{-} in the parameter string of the @option{-gnaty}
+option will be threated as canceling indentation check. The same is true
+for @option{M} parameter. @option{y} and @option{N} parameters are not
+allowed after @option{-}.
+
+@item +
+This causes any subsequent options in the string to enable the corresponding
+style check option. That is, it cancels the effect of a previous ^-^REMOVE^,
+if any.
+@end ifclear
+
+@ifset vms
+@item NOxxx
+@emph{Removing style check options}
+If the name of a style check is preceded by @option{NO} then the corresponding
+style check is turned off. For example @option{NOCOMMENTS} turns off style
+checking for comments.
+@end ifset
@end table
@noindent
The switch
@ifclear vms
@option{-gnaty} on its own (that is not
-followed by any letters or digits),
-is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
-options enabled with the exception of @option{-gnatyo},
-@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
+followed by any letters or digits), then the effect is equivalent
+to the use of @option{-gnatyy}, as described above, that is all
+built-in standard style check options are enabled.
+
@end ifclear
@ifset vms
/STYLE_CHECKS=ALL_BUILTIN enables all checking options with
the exception of ORDERED_SUBPROGRAMS, UNNECESSARY_BLANK_LINES,
XTRA_PARENS, and DOS_LINE_ENDINGS. In addition
@end ifset
-an indentation level of 3 is set. This is similar to the standard
-checking option that is used for the GNAT sources.
+
+
The switch
@ifclear vms
(such as dividing 0.0 by 0.0).
The reason that we distinguish overflow checking from other kinds of
-range constraint checking is that a failure of an overflow check can
-generate an incorrect value, but cannot cause erroneous behavior. This
-is unlike the situation with a constraint check on an array subscript,
-where failure to perform the check can result in random memory description,
-or the range check on a case statement, where failure to perform the check
-can cause a wild jump.
+range constraint checking is that a failure of an overflow check, unlike
+for example the failure of a range check, can result in an incorrect
+value, but cannot cause random memory destruction (like an out of range
+subscript), or a wild jump (from an out of range case value). Overflow
+checking is also quite expensive in time and space, since in general it
+requires the use of double length arithmetic.
Note again that @option{-gnato} is off by default, so overflow checking is
not performed in default mode. This means that out of the box, with the
easily understood by an Ada programmer. The following special syntactic
additions correspond to low level features used in the generated code that
do not have any exact analogies in pure Ada source form. The following
-is a partial list of these special constructions. See the specification
+is a partial list of these special constructions. See the spec
of package @code{Sprint} in file @file{sprint.ads} for a full list.
If the switch @option{-gnatL} is used in conjunction with
in the expanded source (as comment lines with the original line number).
@table @code
-@item new @var{xxx} [storage_pool = @var{yyy}]
+@item new @var{xxx} @r{[}storage_pool = @var{yyy}@r{]}
Shows the storage pool being used for an allocator.
@item at end @var{procedure-name};
A division or multiplication of fixed-point values which are treated as
integers without any kind of scaling.
-@item free @var{expr} [storage_pool = @var{xxx}]
+@item free @var{expr} @r{[}storage_pool = @var{xxx}@r{]}
Shows the storage pool associated with a @code{free} statement.
@item [subtype or type declaration]
Used to list an equivalent declaration for an internally generated
type that is referenced elsewhere in the listing.
-@item freeze @var{type-name} [@var{actions}]
+@item freeze @var{type-name} @ovar{actions}
Shows the point at which @var{type-name} is frozen, with possible
associated actions to be performed at the freeze point.
@option{-gnatDG}, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
+@item -gnatr
+@cindex @option{-gnatr} (@command{gcc})
+@cindex pragma Restrictions
+This switch causes pragma Restrictions to be treated as Restriction_Warnings
+so that violation of restrictions causes warnings rather than illegalities.
+This is useful during the development process when new restrictions are added
+or investigated. The switch also causes pragma Profile to be treated as
+Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
+restriction warnings rather than restrictions.
+
@ifclear vms
-@item -gnatR[0|1|2|3[s]]
+@item -gnatR@r{[}0@r{|}1@r{|}2@r{|}3@r{[}s@r{]]}
@cindex @option{-gnatR} (@command{gcc})
This switch controls output from the compiler of a listing showing
representation information for declared types and objects. For
A mapping file is a sequence of sets of three lines. In each set,
the first line is the unit name, in lower case, with ``@code{%s}''
appended for
-specifications and ``@code{%b}'' appended for bodies; the second line is the
+specs and ``@code{%b}'' appended for bodies; the second line is the
file name; and the third line is the path name.
Example:
-- list all symbols with their values.
@end smallexample
-@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
+@item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=value@r{]}
@cindex @option{-gnateD} (@command{gcc})
Define or redefine a preprocessing symbol, associated with value. If no value
is given on the command line, then the value of the symbol is @code{True}.
The form of the @code{gnatbind} command is
@smallexample
-$ gnatbind [@i{switches}] @i{mainprog}[.ali] [@i{switches}]
+$ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches}
@end smallexample
@noindent
-where @file{@i{mainprog}.adb} is the Ada file containing the main program
+where @file{@var{mainprog}.adb} is the Ada file containing the main program
unit body. If no switches are specified, @code{gnatbind} constructs an Ada
package in two files whose names are
-@file{b~@i{mainprog}.ads}, and @file{b~@i{mainprog}.adb}.
+@file{b~@var{mainprog}.ads}, and @file{b~@var{mainprog}.adb}.
For example, if given the
parameter @file{hello.ali}, for a main program contained in file
@file{hello.adb}, the binder output files would be @file{b~hello.ads}
@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatbind})
Generate binder program in C
-@item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}[k|m]
-@cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}[k|m]} (@command{gnatbind})
+@item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}
+@cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}} (@command{gnatbind})
This switch can be used to change the default task stack size value
to a specified size @var{nn}, which is expressed in bytes by default, or
in kilobytes when suffixed with @var{k} or in megabytes when suffixed
with @var{m}.
-In the absence of a [k|m] suffix, this switch is equivalent, in effect,
-to completing all task specs with
+In the absence of a @samp{@r{[}k@r{|}m@r{]}} suffix, this switch is equivalent,
+in effect, to completing all task specs with
@smallexample @c ada
pragma Storage_Size (nn);
@end smallexample
When they do not already have such a pragma.
-@item ^-D^/DEFAULT_SECONDARY_STACK_SIZE=^@var{nn}[k|m]
+@item ^-D^/DEFAULT_SECONDARY_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}
@cindex @option{^-D^/DEFAULT_SECONDARY_STACK_SIZE=nnnnn^} (@command{gnatbind})
This switch can be used to change the default secondary stack size value
to a specified size @var{nn}, which is expressed in bytes by default, or
The form of the @command{gnatlink} command is
@smallexample
-$ gnatlink [@var{switches}] @var{mainprog}[.ali]
- [@var{non-Ada objects}] [@var{linker options}]
+$ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]}
+ @ovar{non-Ada objects} @ovar{linker options}
@end smallexample
@noindent
Using @var{linker options} it is possible to set the program stack and
heap size.
-@ifclear vms
+@ifset unw
See @ref{Setting Stack Size from gnatlink} and
@ref{Setting Heap Size from gnatlink}.
-@end ifclear
+@end ifset
@command{gnatlink} determines the list of objects required by the Ada
program and prepends them to the list of objects passed to the linker.
inserted after your command name. Thus in the above example the compiler
command that will be used by @command{gnatlink} will be @code{foo -c -x -y}.
A limitation of this syntax is that the name and path name of the executable
-itself must not include any embedded spaces. If several
+itself must not include any embedded spaces. If the compiler executable is
+different from the default one (gcc or <prefix>-gcc), then the back-end
+switches in the ALI file are not used to compile the binder generated source.
+For example, this is the case with @option{--GCC="foo -x -y"}. But the back end
+switches will be used for @option{--GCC="gcc -gnatv"}. If several
@option{--GCC=compiler_name} are used, only the last @var{compiler_name}
is taken into account. However, all the additional switches are also taken
into account. Thus,
The usual form of the @command{gnatmake} command is
@smallexample
-$ gnatmake [@var{switches}] @var{file_name}
- [@var{file_names}] [@var{mode_switches}]
+$ gnatmake @ovar{switches} @var{file_name}
+ @ovar{file_names} @ovar{mode_switches}
@end smallexample
@noindent
Compile only. Do not perform binding, except when @option{^-b^/ACTIONS=BIND^}
is also specified. Do not perform linking, except if both
@option{^-b^/ACTIONS=BIND^} and
- @option{^-l^/ACTIONS=LINK^} are also specified.
+@option{^-l^/ACTIONS=LINK^} are also specified.
If the root unit specified by @var{file_name} is not a main unit, this is the
default. Otherwise @command{gnatmake} will attempt binding and linking
unless all objects are up to date and the executable is more recent than
(^-P^/PROJECT_FILE=^@var{file}) or with multiple compiling processes
(^-j^/PROCESSES=^nnn, when nnn is greater than 1).
+@item ^-d^/DISPLAY_PROGRESS^
+@cindex @option{^-d^/DISPLAY_PROGRESS^} (@command{gnatmake})
+Display progress for each source, up to date or not, as a single line
+
+@smallexample
+completed x out of y (zz%)
+@end smallexample
+
+If the file needs to be compiled this is displayed after the invocation of
+the compiler. These lines are displayed even in quiet output mode.
+
@item ^-D ^/DIRECTORY_OBJECTS=^@var{dir}
@cindex @option{^-D^/DIRECTORY_OBJECTS^} (@command{gnatmake})
Put all object files and ALI file in directory @var{dir}.
File may be compile. When this switch is used, a source outside of all Project
Files may be compiled. The ALI file and the object file will be put in the
object directory of the main Project. The compilation switches used will only
-be those specified on the command line.
+be those specified on the command line. Even when
+@option{^-x^/NON_PROJECT_UNIT_COMPILATION^} is used, mains specified on the
+command line need to be sources of a project file.
@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
Indicate that external variable @var{name} has the value @var{value}.
@ifset vms
@item gnatmake Main_Unit /QUIET
- /COMPILER_QUALIFIERS /OPTIMIZE=ALL
- /BINDER_QUALIFIERS /ORDER_OF_ELABORATION
+/COMPILER_QUALIFIERS /OPTIMIZE=ALL
+/BINDER_QUALIFIERS /ORDER_OF_ELABORATION
@end ifset
Compile all files necessary to bind and link the main program unit
@code{Main_Unit} (from file @file{main_unit.adb}). All compilations will
@ifnottex
@menu
* Performance Considerations::
+* Text_IO Suggestions::
* Reducing Size of Ada Executables with gnatelim::
* Reducing Size of Executables with unused subprogram/data elimination::
@end menu
@cindex @option{^-O^/OPTIMIZE^} (@command{gcc})
@noindent
+Without any optimization ^option,^qualifier,^
+the compiler's goal is to reduce the cost of
+compilation and to make debugging produce the expected results.
+Statements are independent: if you stop the program with a breakpoint between
+statements, you can then assign a new value to any variable or change
+the program counter to any other statement in the subprogram and get exactly
+the results you would expect from the source code.
+
+Turning on optimization makes the compiler attempt to improve the
+performance and/or code size at the expense of compilation time and
+possibly the ability to debug the program.
+
+If you use multiple
+^-O options, with or without level numbers,^/OPTIMIZE qualifiers,^
+the last such option is the one that is effective.
+
+@noindent
The default is optimization off. This results in the fastest compile
times, but GNAT makes absolutely no attempt to optimize, and the
generated programs are considerably larger and slower than when
the fastest compilation time.
Note that many other compilers do fairly extensive optimization
-even if "no optimization" is specified. When using gcc, it is
+even if ``no optimization'' is specified. With gcc, it is
very unusual to use ^-O0^/OPTIMIZE=NONE^ for production if
execution time is of any concern, since ^-O0^/OPTIMIZE=NONE^
really does mean no optimization at all. This difference between
both depend on the particular application and the hardware environment.
You should experiment to find the best level for your application.
-The @option{^-Os^/OPTIMIZE=SPACE^} switch is independent of the time
-optimizations, so you can specify both @option{^-Os^/OPTIMIZE=SPACE^}
-and a time optimization on the same compile command.
-
Since the precise set of optimizations done at each level will vary from
release to release (and sometime from target to target), it is best to think
of the optimization settings in general terms.
@item
The called subprogram is suitable for inlining: It must be small enough
-and not contain nested subprograms or anything else that @command{gcc}
-cannot support in inlined subprograms.
-
-@item
-The call occurs after the definition of the body of the subprogram.
+and not contain something that @command{gcc} cannot support in inlined
+subprograms.
@item
@cindex pragma Inline
@findex Inline
-Either @code{pragma Inline} applies to the subprogram or it is
-small and automatic inlining (optimization level @option{-O3}) is
-specified.
+Either @code{pragma Inline} applies to the subprogram, or it is local
+to the unit and called once from within it, or it is small and automatic
+inlining (optimization level @option{-O3}) is specified.
@end itemize
@noindent
@item
The called subprogram is suitable for inlining: It must be small enough
-and not contain nested subprograms or anything else @command{gcc} cannot
-support in inlined subprograms.
+and not contain something that @command{gcc} cannot support in inlined
+subprograms.
@item
The call appears in a body (not in a package spec).
@option{-gnatn} will still be active, even if
this switch is used to suppress the resulting inlining actions.
+@cindex @option{-fno-inline-functions} (@command{gcc})
+Note: The @option{-fno-inline-functions} switch can be used to prevent
+automatic inlining of small subprograms if @option{-O3} is used.
+
+@cindex @option{-fno-inline-functions-called-once} (@command{gcc})
+Note: The @option{-fno-inline-functions-called-once} switch
+can be used to prevent inlining of subprograms local to the unit
+and called once from within it if @option{-O1} is used.
+
Note regarding the use of @option{-O3}: There is no difference in inlining
behavior between @option{-O2} and @option{-O3} for subprograms with an explicit
pragma @code{Inline} assuming the use of @option{-gnatn}
@pxref{Profiling} for details of usage.
@end ifset
+
+@node Text_IO Suggestions
+@section @code{Text_IO} Suggestions
+@cindex @code{Text_IO} and performance
+
+@noindent
+The @code{Ada.Text_IO} package has fairly high overheads due in part to
+the requirement of maintaining page and line counts. If performance
+is critical, a recommendation is to use @code{Stream_IO} instead of
+@code{Text_IO} for volume output, since this package has less overhead.
+
+If @code{Text_IO} must be used, note that by default output to the standard
+output and standard error files is unbuffered (this provides better
+behavior when output statements are used for debugging, or if the
+progress of a program is observed by tracking the output, e.g. by
+using the Unix @command{tail -f} command to watch redirected output.
+
+If you are generating large volumes of output with @code{Text_IO} and
+performance is an important factor, use a designated file instead
+of the standard output file, or change the standard output file to
+be buffered using @code{Interfaces.C_Streams.setvbuf}.
+
+
+
@node Reducing Size of Ada Executables with gnatelim
@section Reducing Size of Ada Executables with @code{gnatelim}
@findex gnatelim
@code{gnatelim} has the following command-line interface:
@smallexample
-$ gnatelim [options] name
+$ gnatelim @ovar{options} name
@end smallexample
@noindent
$ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC
@end ifset
@ifclear vms
-$ gnatelim main_prog >[>] gnat.adc
+$ gnatelim main_prog >@r{[}>@r{]} gnat.adc
@end ifclear
@end smallexample
The @code{gnatchop} command has the form:
@smallexample
-$ gnatchop switches @var{file name} [@var{file name} @var{file name} @dots{}]
- [@var{directory}]
+$ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]}
+ @ovar{directory}
@end smallexample
@noindent
Ada_83
Ada_95
Ada_05
+ Ada_2005
+ Assertion_Policy
C_Pass_By_Copy
+ Check_Name
+ Check_Policy
+ Compile_Time_Error
+ Compile_Time_Warning
+ Compiler_Unit
Component_Alignment
+ Debug_Policy
Detect_Blocking
Discard_Names
Elaboration_Checks
Eliminate
Extend_System
External_Name_Casing
+ Fast_Math
+ Favor_Top_Level
Float_Representation
+ Implicit_Packing
Initialize_Scalars
Interrupt_State
License
Locking_Policy
Long_Float
+ No_Run_Time
+ No_Strict_Aliasing
Normalize_Scalars
+ Optimize_Alignment
Persistent_BSS
Polling
+ Priority_Specific_Dispatching
Profile
Profile_Warnings
Propagate_Exceptions
Restrictions_Warnings
Reviewable
Source_File_Name
+ Source_File_Name_Project
Style_Checks
Suppress
+ Suppress_Exception_Locations
Task_Dispatching_Policy
Universal_Data
Unsuppress
Use_VADS_Size
- Warnings
Validity_Checks
+ Warnings
+ Wide_Character_Encoding
+
@end smallexample
@menu
The usual form of the @code{gnatname} command is
@smallexample
-$ gnatname [@var{switches}] @var{naming_pattern} [@var{naming_patterns}]
+$ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}
+ @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]}
@end smallexample
@noindent
used in file names by the Unix shells or the DOS prompt.
@noindent
+@code{gnatname} may be called with several sections of directories/patterns.
+Sections are separated by switch @code{--and}. In each section, there must be
+at least one pattern. If no directory is specified in a section, the current
+directory (or the project directory is @code{-P} is used) is implied.
+The options other that the directory switches and the patterns apply globally
+even if they are in different sections.
+
+@noindent
Examples of Naming Patterns are
@smallexample
(the ``Glob'' regular expressions).
@noindent
-When invoked with no switches, @code{gnatname} will create a configuration
-pragmas file @file{gnat.adc} in the current working directory, with pragmas
-@code{Source_File_Name} for each file that contains a valid Ada unit.
+When invoked with no switch @code{-P}, @code{gnatname} will create a
+configuration pragmas file @file{gnat.adc} in the current working directory,
+with pragmas @code{Source_File_Name} for each file that contains a valid Ada
+unit.
@node Switches for gnatname
@section Switches for @code{gnatname}
If @option{--version} was not used, display usage, then exit disregarding
all other options.
+@item --and
+Start another section of directories/patterns.
+
@item ^-c^/CONFIG_FILE=^@file{file}
@cindex @option{^-c^/CONFIG_FILE^} (@code{gnatname})
Create a configuration pragmas file @file{file} (instead of the default
@noindent
In large software systems it is common to have multiple
implementations of a common interface; in Ada terms, multiple versions of a
-package body for the same specification. For example, one implementation
+package body for the same spec. For example, one implementation
might be safe for use in tasking programs, while another might only be used
in sequential applications. This can be modeled in GNAT using the concept
of @emph{project extension}. If one project (the ``child'') @emph{extends}
will be a compilation error when compiling the spec.
For that purpose, the attribute @code{Excluded_Source_Files} is used.
-Its value is a string list: a list of file names.
+Its value is a string list: a list of file names. It is also possible to use
+attribute @code{Excluded_Source_List_File}. Its value is a single string:
+the file name of a text file containing a list of file names, one per line.
@smallexample @c @projectfile
project B extends "a" is
@menu
* Basic Syntax::
+* Qualified Projects::
* Packages::
* Expressions::
* String Types::
Any name in a project file, such as the project name or a variable name,
has the same syntax as an Ada identifier.
-The reserved words of project files are the Ada reserved words plus
+The reserved words of project files are the Ada 95 reserved words plus
@code{extends}, @code{external}, and @code{project}. Note that the only Ada
reserved words currently used in project file syntax are:
@itemize @bullet
@item
+@code{all}
+@item
+@code{at}
+@item
@code{case}
@item
@code{end}
@item
@code{is}
@item
+@code{limited}
+@item
+@code{null}
+@item
@code{others}
@item
@code{package}
Comments in project files have the same syntax as in Ada, two consecutive
hyphens through the end of the line.
+@node Qualified Projects
+@subsection Qualified Projects
+
+@noindent
+Before the reserved @code{project}, there may be one or two "qualifiers", that
+is identifiers or other reserved words, to qualify the project.
+
+The current list of qualifiers is:
+
+@itemize @bullet
+@item
+@code{abstract}: qualify a project with no sources. An abstract project must
+have a declaration specifying that there are no sources in the project, and,
+if it extends another project, the project it extends must also be a qualified
+abstract project.
+
+@item
+@code{standard}: a standard project is a non library project with sources.
+
+@item
+@code{aggregate}: for future extension
+
+@item
+@code{aggregate library}: for future extension
+
+@item
+@code{library}: a library project must declare both attributes
+@code{Library_Name} and @code{Library_Dir}.
+
+@item
+@code{configuration}: a configuration project cannot be in a project tree.
+@end itemize
+
@node Packages
@subsection Packages
@tab string list
@item @code{Excluded_Source_Files}
@tab string list
+@item @code{Excluded_Source_List_File}
+@tab string
@item @code{Languages}
@tab string list
@item @code{Main}
@item The name of an imported project
@item The name of a parent project that is extended by the current project
@item An expanded name whose prefix is imported/parent project name,
- and whose selector is a package name
+and whose selector is a package name
@end itemize
@noindent
An inherited source file retains any switches specified in the parent project.
-For example if the project @code{Utilities} contains the specification and the
+For example if the project @code{Utilities} contains the spec and the
body of an Ada package @code{Util_IO}, then the project
@code{Modified_Utilities} can contain a new body for package @code{Util_IO}.
The original body of @code{Util_IO} will not be considered in program builds.
-However, the package specification will still be found in the project
+However, the package spec will still be found in the project
@code{Utilities}.
-A child project can have only one parent but it may import any number of other
-projects.
+A child project can have only one parent, except when it is qualified as
+abstract. But it may import any number of other projects.
A project is not allowed to import directly or indirectly at the same time a
child project and any of its ancestors.
@table @option
@item ^-P^/PROJECT_FILE=^@var{project}
-@cindex @option{^-P^/PROJECT_FILE^} (any tool supporting project files)
+@cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
Indicates the name of a project file. This project file will be parsed with
the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
if any, and using the external references indicated
or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
-@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any tool supporting project files)
+@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
Indicates that external variable @var{name} has the value @var{value}.
The Project Manager will use this value for occurrences of
@code{external(name)} when parsing the project file.
takes precedence over the value of the same name in the environment.
@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
-@cindex @code{^-vP^/MESSAGES_PROJECT_FILE^} (any tool supporting project files)
-@c Previous line uses code vs option command, to stay less than 80 chars
+@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
Indicates the verbosity of the parsing of GNAT project files.
@ifclear vms
If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
only the last one is used.
+@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
+@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
+Add directory <dir> at the beginning of the project search path, in order,
+after the current working directory.
+
+@ifclear vms
+@item -eL
+@cindex @option{-eL} (any project-aware tool)
+Follow all symbolic links when processing project files.
+@end ifclear
+
+@item ^--subdirs^/SUBDIRS^=<subdir>
+@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
+This switch is recognized by gnatmake and gnatclean. It indicate that the real
+directories (except the source directories) are the subdirectories <subdir>
+of the directories specified in the project files. This applies in particular
+to object directories, library directories and exec directories. If the
+subdirectories do not exist, they are created automatically.
+
@end table
@c **********************************
other_declarative_item
package_declaration ::=
- package_specification | package_renaming
+ package_spec | package_renaming
-package_specification ::=
+package_spec ::=
@b{package} package_identifier @b{is}
@{simple_declarative_item@}
@b{end} package_identifier ;
@noindent
The command invocation for @code{gnatxref} is:
@smallexample
-$ gnatxref [switches] sourcefile1 [sourcefile2 @dots{}]
+$ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
@end smallexample
@noindent
where
-@table @code
-@item sourcefile1, sourcefile2
+@table @var
+@item sourcefile1
+@itemx sourcefile2
identifies the source files for which a report is to be generated. The
``with''ed units will be processed too. You must provide at least one file.
The command line for @code{gnatfind} is:
@smallexample
-$ gnatfind [switches] pattern[:sourcefile[:line[:column]]]
- [file1 file2 @dots{}]
+$ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
+ @r{[}@var{file1} @var{file2} @dots{}]
@end smallexample
@noindent
where
-@table @code
+@table @var
@item pattern
An entity will be output only if it matches the regular expression found
-in @samp{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}.
+in @var{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}.
Omitting the pattern is equivalent to specifying @samp{*}, which
will match any entity. Note that if you do not provide a pattern, you
@item sourcefile
@code{gnatfind} will look for references, bodies or declarations
-of symbols referenced in @file{sourcefile}, at line @samp{line}
-and column @samp{column}. See @ref{Examples of gnatfind Usage}
+of symbols referenced in @file{@var{sourcefile}}, at line @var{line}
+and column @var{column}. See @ref{Examples of gnatfind Usage}
for syntax examples.
@item line
@file{adb}.
The location of the spec of the entity will always be displayed, even if it
-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.
+isn't in one of @file{@var{file1}}, @file{@var{file2}},@enddots{} The
+occurrences of the entity in the separate units of the ones given on the
+command line will also be displayed.
Note that if you specify at least one file in this part, @code{gnatfind} may
sometimes not be able to find the body of the subprograms.
@ifclear vms
@item make_cmd=COMMAND
[default: @code{"gnatmake $@{main@} -aI$@{src_dir@}
- -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@}
- -bargs $@{bind_opt@} -largs $@{link_opt@}"}]
+-aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@}
+-bargs $@{bind_opt@} -largs $@{link_opt@}"}]
@end ifclear
specifies the command used to recompile the whole application.
will generate the tags file for @code{gnatfind} itself (if the sources
are in the search path!).
-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
+From @command{vi}, you can then use the command @samp{:tag @var{entity}}
+(replacing @var{entity} by whatever you are looking for), and vi will
display a new file with the corresponding declaration of entity.
@end ifclear
The @command{gnatpp} command has the form
@smallexample
-$ gnatpp [@var{switches}] @var{filename}
+$ gnatpp @ovar{switches} @var{filename}
@end smallexample
@noindent
@cindex @option{^--no-separate-is^/NO_SEPARATE_IS^} (@command{gnatpp})
@item ^--no-separate-is^/NO_SEPARATE_IS^
Do not place the keyword @code{is} on a separate line in a subprogram body in
-case if the specification occupies more then one line.
+case if the spec occupies more then one line.
@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
These switches allow control over line length and indentation.
@table @option
-@item ^-M@i{nnn}^/LINE_LENGTH_MAX=@i{nnn}^
+@item ^-M@var{nnn}^/LINE_LENGTH_MAX=@var{nnn}^
@cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp})
-Maximum line length, @i{nnn} from 32@dots{}256, the default value is 79
+Maximum line length, @var{nnn} from 32@dots{}256, the default value is 79
-@item ^-i@i{nnn}^/INDENTATION_LEVEL=@i{nnn}^
+@item ^-i@var{nnn}^/INDENTATION_LEVEL=@var{nnn}^
@cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp})
-Indentation level, @i{nnn} from 1@dots{}9, the default value is 3
+Indentation level, @var{nnn} from 1@dots{}9, the default value is 3
-@item ^-cl@i{nnn}^/CONTINUATION_INDENT=@i{nnn}^
+@item ^-cl@var{nnn}^/CONTINUATION_INDENT=@var{nnn}^
@cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp})
Indentation level for continuation lines (relative to the line being
-continued), @i{nnn} from 1@dots{}9.
+continued), @var{nnn} from 1@dots{}9.
The default
value is one less then the (normal) indentation level, unless the
indentation is set to 1 (in which case the default value for continuation
@cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp})
Insert a Form Feed character after a pragma Page.
-@item ^-T@i{nnn}^/MAX_INDENT=@i{nnn}^
+@item ^-T@var{nnn}^/MAX_INDENT=@var{nnn}^
@cindex @option{^-T^/MAX_INDENT^} (@command{gnatpp})
Do not use an additional indentation level for @b{case} alternatives
-and variants if there are @i{nnn} or more (the default
+and variants if there are @var{nnn} or more (the default
value is 10).
-If @i{nnn} is 0, an additional indentation level is
+If @var{nnn} is 0, an additional indentation level is
used for @b{case} alternatives and variants regardless of their number.
@end table
Like @option{^-r^/REPLACE^} except that if the file with the specified name
already exists, it is overwritten.
-@item ^-rnb^/NO_BACKUP^
-@cindex @option{^-rnb^/NO_BACKUP^} (@code{gnatpp})
+@item ^-rnb^/REPLACE_NO_BACKUP^
+@cindex @option{^-rnb^/REPLACE_NO_BACKUP^} (@code{gnatpp})
Replace the input source file with the reformatted output without
creating any backup copy of the input source.
The @command{gnatmetric} command has the form
@smallexample
-$ gnatmetric [@i{switches}] @{@i{filename}@} [@i{-cargs gcc_switches}]
+$ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
@end smallexample
@noindent
where
@itemize @bullet
@item
-@i{switches} specify the metrics to compute and define the destination for
+@var{switches} specify the metrics to compute and define the destination for
the output
@item
-Each @i{filename} is the name (including the extension) of a source
+Each @var{filename} is the name (including the extension) of a source
file to process. ``Wildcards'' are allowed, and
the file name may contain path information.
-If no @i{filename} is supplied, then the @i{switches} list must contain
+If no @var{filename} is supplied, then the @var{switches} list must contain
at least one
@option{-files} switch (@pxref{Other gnatmetric Switches}).
Including both a @option{-files} switch and one or more
-@i{filename} arguments is permitted.
+@var{filename} arguments is permitted.
@item
-@i{-cargs gcc_switches} is a list of switches for
+@samp{-cargs @var{gcc_switches}} is a list of switches for
@command{gcc}. They will be passed on to all compiler invocations made by
@command{gnatmetric} to generate the ASIS trees. Here you can provide
@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
subprogram (and generic subprogram) bodies;
@item
-package (and generic package) specifications and bodies;
+package (and generic package) specs and bodies;
@item
task object and type specifications and bodies;
* Line Metrics Control::
* Syntax Metrics Control::
* Complexity Metrics Control::
+* Object-Oriented Metrics Control::
@end menu
@node Line Metrics Control
@table @emph
@item Public subprograms
-This metric is computed for package specifications. It is the
+This metric is computed for package specs. It is the
number of subprograms and generic subprograms declared in the visible
part (including the visible part of nested packages, protected objects, and
protected types).
subprograms are counted in the same way as ``usual'' subprogram bodies.
@item Public types
-This metric is computed for package specifications and
+This metric is computed for package specs and
generic package declarations. It is the total number of types
that can be referenced from outside this compilation unit, plus the
number of types from all the visible parts of all the visible generic
@cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric})
@ifclear vms
-@cindex @option{--no-syntax@var{x}}
+@cindex @option{--no-syntax@var{x}} (@command{gnatmetric})
@end ifclear
@item ^--syntax-all^/SYNTAX_METRICS=ALL_ON^
@end table
+
+@node Object-Oriented Metrics Control
+@subsubsection Object-Oriented Metrics Control
+@cindex Object-Oriented metrics control in @command{gnatmetric}
+
+@noindent
+@cindex Coupling metrics (in in @command{gnatmetric})
+Coupling metrics are object-oriented metrics that measure the
+dependencies between a given class (or a group of classes) and the
+``external world'' (that is, the other classes in the program). In this
+subsection the term ``class'' is used in its
+traditional object-oriented programming sense
+(an instantiable module that contains data and/or method members).
+A @emph{category} (of classes)
+is a group of closely related classes that are reused and/or
+modified together.
+
+A class @code{K}'s @emph{efferent coupling} is the number of classes
+that @code{K} depends upon.
+A category's efferent coupling is the number of classes outside the
+category that the classes inside the category depend upon.
+
+A class @code{K}'s @emph{afferent coupling} is the number of classes
+that depend upon @code{K}.
+A category's afferent coupling is the number of classes outside the
+category that depend on classes belonging to the category.
+
+Ada's implementation of the object-oriented paradigm does not use the
+traditional class notion, so the definition of the coupling
+metrics for Ada maps the class and class category notions
+onto Ada constructs.
+
+For the coupling metrics, several kinds of modules -- a library package,
+a library generic package, and a library generic package instantiation --
+that define a tagged type or an interface type are
+considered to be a class. A category consists of a library package (or
+a library generic package) that defines a tagged or an interface type,
+together with all its descendant (generic) packages that define tagged
+or interface types. For any package counted as a class,
+its body (if any) is considered
+together with its spec when counting the dependencies. For dependencies
+between classes, the Ada semantic dependencies are considered.
+For coupling metrics, only dependencies on units that are considered as
+classes, are considered.
+
+When computing coupling metrics, @command{gnatmetric} counts only
+dependencies between units that are arguments of the gnatmetric call.
+Coupling metrics are program-wide (or project-wide) metrics, so to
+get a valid result, you should call @command{gnatmetric} for
+the whole set of sources that make up your program. It can be done
+by calling @command{gnatmetric} from the GNAT driver with @option{-U}
+option (see See @ref{The GNAT Driver and Project Files} for details.
+
+By default, all the coupling metrics are disabled. You can use the following
+switches to specify the coupling metrics to be computed and reported:
+
+@table @option
+
+@ifclear vms
+@cindex @option{--package@var{x}} (@command{gnatmetric})
+@cindex @option{--no-package@var{x}} (@command{gnatmetric})
+@cindex @option{--category@var{x}} (@command{gnatmetric})
+@cindex @option{--no-category@var{x}} (@command{gnatmetric})
+@end ifclear
+
+@ifset vms
+@cindex @option{/COUPLING_METRICS} (@command{gnatmetric})
+@end ifset
+
+@item ^--coupling-all^/COUPLING_METRICS=ALL_ON^
+Report all the coupling metrics
+
+@item ^--no-coupling-all^/COUPLING_METRICS=ALL_OFF^
+Do not report any of metrics
+
+@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_ON^
+Report package efferent coupling
+
+@item ^--no-package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_OFF^
+Do not report package efferent coupling
+
+@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_ON^
+Report package afferent coupling
+
+@item ^--no-package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_OFF^
+Do not report package afferent coupling
+
+@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_ON^
+Report category efferent coupling
+
+@item ^--no-category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_OFF^
+Do not report category efferent coupling
+
+@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_ON^
+Report category afferent coupling
+
+@item ^--no-category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_OFF^
+Do not report category afferent coupling
+
+@end table
+
@node Other gnatmetric Switches
@subsection Other @code{gnatmetric} Switches
@ifclear vms
@smallexample
-$ gnatkr @var{name} [@var{length}]
+$ gnatkr @var{name} @ovar{length}
@end smallexample
@end ifclear
replaced by a ^tilde^dollar sign^ if the first character is
^@samp{a}, @samp{i}, @samp{g}, or @samp{s}^@samp{A}, @samp{I}, @samp{G}, or @samp{S}^.
The extension is @code{.ads} for a
-specification and @code{.adb} for a body.
+spec and @code{.adb} for a body.
Krunching does not affect the extension, but the file name is shortened to
the specified length by following these rules:
@ref{Conditional Compilation}.
@menu
+* Preprocessing Symbols::
* Using gnatprep::
* Switches for gnatprep::
* Form of Definitions File::
* Form of Input Text for gnatprep::
@end menu
+@node Preprocessing Symbols
+@section Preprocessing Symbols
+
+@noindent
+Preprocessing symbols are defined in definition files and referred to in
+sources to be preprocessed. A Preprocessing symbol is an identifier, following
+normal Ada (case-insensitive) rules for its syntax, with the restriction that
+all characters need to be in the ASCII set (no accented letters).
@node Using gnatprep
@section Using @code{gnatprep}
To call @code{gnatprep} use
@smallexample
-$ gnatprep [switches] infile outfile [deffile]
+$ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile}
@end smallexample
@noindent
where
-@table @code
+@table @var
@item switches
is an optional sequence of switches as described in the next section.
@item deffile
is the full name of a text file containing definitions of
-symbols to be referenced by the preprocessor. This argument is
+preprocessing symbols to be referenced by the preprocessor. This argument is
optional, and can be replaced by the use of the @option{-D} switch.
@end table
@item ^-Dsymbol=value^/ASSOCIATE="symbol=value"^
@cindex @option{^-D^/ASSOCIATE^} (@command{gnatprep})
-Defines a new symbol, associated with value. If no value is given on the
-command line, then symbol is considered to be @code{True}. This switch
+Defines a new preprocessing symbol, associated with value. If no value is given
+on the command line, then symbol is considered to be @code{True}. This switch
can be used in place of a definition file.
@ifset vms
@end smallexample
@noindent
-where symbol is an identifier, following normal Ada (case-insensitive)
-rules for its syntax, and value is one of the following:
+where symbol is a preprocessing symbol, and value is one of the following:
@itemize @bullet
@item
@smallexample
@group
@cartouche
-#if @i{expression} [then]
+#if @i{expression} @r{[}then@r{]}
lines
-#elsif @i{expression} [then]
+#elsif @i{expression} @r{[}then@r{]}
lines
-#elsif @i{expression} [then]
+#elsif @i{expression} @r{[}then@r{]}
lines
@dots{}
#else
@i{expression} ::= ( @i{expression} )
@end smallexample
+The following restriction exists: it is not allowed to have "and" or "or"
+following "not" in the same expression without parentheses. For example, this
+is not allowed:
+
+@smallexample
+ not X or Y
+@end smallexample
+
+This should be one of the following:
+
+@smallexample
+ (not X) or Y
+ not (X or Y)
+@end smallexample
+
@noindent
For the first test (@i{expression} ::= <symbol>) the symbol must have
either the value true or false, that is to say the right-hand of the
The @code{gnatlbr} command has the form
@smallexample
-$ GNAT LIBRARY /[CREATE | SET | DELETE]=directory [/CONFIG=file]
+$ GNAT LIBRARY /@r{[}CREATE@r{|}SET@r{|}DELETE@r{]}=directory @r{[}/CONFIG=file@r{]}
@end smallexample
@node Switches for gnatlbr
@c !sort!
@item /CREATE=directory
@cindex @code{/CREATE} (@code{gnatlbr})
- Create the new run-time library in the specified directory.
+Create the new run-time library in the specified directory.
@item /SET=directory
@cindex @code{/SET} (@code{gnatlbr})
- Make the library in the specified directory the current run-time
- library.
+Make the library in the specified directory the current run-time library.
@item /DELETE=directory
@cindex @code{/DELETE} (@code{gnatlbr})
- Delete the run-time library in the specified directory.
+Delete the run-time library in the specified directory.
@item /CONFIG=file
@cindex @code{/CONFIG} (@code{gnatlbr})
- With /CREATE:
- Use the configuration pragmas in the specified file when building
- the library.
+With /CREATE: Use the configuration pragmas in the specified file when
+building the library.
- With /SET:
- Use the configuration pragmas in the specified file when compiling.
+With /SET: Use the configuration pragmas in the specified file when
+compiling.
@end table
The @code{gnatmem} command has the form
@smallexample
- $ gnatmem [switches] user_program
+ $ gnatmem @ovar{switches} user_program
@end smallexample
@noindent
Invoking @command{gnatcheck} on the command line has the form:
@smallexample
-$ gnatcheck [@i{switches}] @{@i{filename}@}
- [^-files^/FILES^=@{@i{arg_list_filename}@}]
- [-cargs @i{gcc_switches}] [-rules @i{rule_options}]
+$ gnatcheck @ovar{switches} @{@var{filename}@}
+ @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
+ @r{[}-cargs @var{gcc_switches}@r{]} @r{[}-rules @var{rule_options}@r{]}
@end smallexample
@noindent
where
@itemize @bullet
@item
-@i{switches} specify the general tool options
+@var{switches} specify the general tool options
@item
-Each @i{filename} is the name (including the extension) of a source
+Each @var{filename} is the name (including the extension) of a source
file to process. ``Wildcards'' are allowed, and
the file name may contain path information.
@item
-Each @i{arg_list_filename} is the name (including the extension) of a text
+Each @var{arg_list_filename} is the name (including the extension) of a text
file containing the names of the source files to process, separated by spaces
or line breaks.
@item
-@i{gcc_switches} is a list of switches for
+@var{gcc_switches} is a list of switches for
@command{gcc}. They will be passed on to all compiler invocations made by
@command{gnatcheck} to generate the ASIS trees. Here you can provide
@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
and use the @option{-gnatec} switch to set the configuration file.
@item
-@i{rule_options} is a list of options for controlling a set of
+@var{rule_options} is a list of options for controlling a set of
rules to be checked by @command{gnatcheck} (@pxref{gnatcheck Rule Options}).
@end itemize
@noindent
-Either a @i{filename} or an @i{arg_list_filename} must be supplied.
+Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be supplied.
@menu
* Format of the Report File::
Turn all the rule checks OFF.
@cindex @option{+R} (@command{gnatcheck})
-@item +R@i{rule_id[:param]}
+@item +R@var{rule_id}@r{[}:@var{param}@r{]}
Turn on the check for a specified rule with the specified parameter, if any.
-@i{rule_id} must be the identifier of one of the currently implemented rules
+@var{rule_id} must be the identifier of one of the currently implemented rules
(use @option{^-h^/HELP^} for the list of implemented rules). Rule identifiers
-are not case-sensitive. The @i{param} item must
+are not case-sensitive. The @var{param} item must
be a string representing a valid parameter(s) for the specified rule.
If it contains any space characters then this string must be enclosed in
quotation marks.
@cindex @option{-R} (@command{gnatcheck})
-@item -R@i{rule_id[:param]}
+@item -R@var{rule_id}@r{[}:@var{param}@r{]}
Turn off the check for a specified rule with the specified parameter, if any.
@cindex @option{-from} (@command{gnatcheck})
-@item -from=@i{rule_option_filename}
-Read the rule options from the text file @i{rule_option_filename}, referred as
+@item -from=@var{rule_option_filename}
+Read the rule options from the text file @var{rule_option_filename}, referred as
``rule file'' below.
@end table
lines and end-of-line comments). The rule file has free format; that is,
you do not have to start a new rule option on a new line.
-A rule file may contain other @option{-from=@i{rule_option_filename}}
+A rule file may contain other @option{-from=@var{rule_option_filename}}
options, each such option being replaced with the content of the
corresponding rule file during the rule files processing. In case a
-cycle is detected (that is, @i{rule_file_1} reads rule options from
-@i{rule_file_2}, and @i{rule_file_2} reads (directly or indirectly)
-rule options from @i{rule_file_1}), the processing
-of rule files is interrupted and a part of their content is ignored.
+cycle is detected (that is, @file{@var{rule_file_1}} reads rule options
+from @file{@var{rule_file_2}}, and @file{@var{rule_file_2}} reads
+(directly or indirectly) rule options from @file{@var{rule_file_1}}),
+the processing of rule files is interrupted and a part of their content
+is ignored.
@node Adding the Results of Compiler Checks to gnatcheck Output
@code{Restrictions} or @code{Restriction_Warnings}.
@item Style_Checks
-To record compiler style checks, use the rule named
+To record compiler style checks(@pxref{Style Checking}), use the rule named
@code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
-which enables all the style checks, or a string that has exactly the same
+which enables all the standard style checks that corresponds to @option{-gnatyy}
+GNAT style check option, or a string that has exactly the same
structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
@code{Style_Checks} (for further information about this pragma,
@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
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, @pxref{Pragma Warnings,,,
-gnat_rm, GNAT Reference Manual}).
+gnat_rm, GNAT Reference Manual}). Note, that in case of gnatcheck
+'s' parameter, that corresponds to the GNAT @option{-gnatws} option, disables
+all the specific warnings, but not suppresses the warning mode,
+and 'e' parameter, corresponding to @option{-gnatwe} that means
+"treat warnings as errors", does not have any effect.
@end table
+To disable a specific restriction check, use @code{-RStyle_Checks} gnatcheck
+option with the corresponding restriction name as a parameter. @code{-R} is
+not available for @code{Style_Checks} and @code{Warnings} options, to disable
+warnings and style checks, use the corresponding warning and style options.
+
@node Project-Wide Checks
@section Project-Wide Checks
@cindex Project-wide checks (for @command{gnatcheck})
@ignore
* Improperly_Called_Protected_Entries::
@end ignore
+* Metrics::
* Misnamed_Identifiers::
* Multiple_Entries_In_Protected_Definitions::
* Name_Clashes::
* Predefined_Numeric_Types::
* Raising_External_Exceptions::
* Raising_Predefined_Exceptions::
+* Separate_Numeric_Error_Handlers::
@ignore
* Recursion::
* Side_Effect_Functions::
@cindex @code{Improperly_Located_Instantiations} rule (for @command{gnatcheck})
@noindent
-Flag all generic instantiations in library-level package specifications
+Flag all generic instantiations in library-level package specs
(including library generic packages) and in all subprogram bodies.
Instantiations in task and entry bodies are not flagged. Instantiations in the
@noindent
Flag all local packages declared in package and generic package
-specifications.
+specs.
Local packages in bodies are not flagged.
This rule has no parameters.
This rule has no parameters.
@end ignore
+@node Metrics
+@subsection @code{Metrics}
+@cindex @code{Metrics} rule (for @command{gnatcheck})
+
+@noindent
+This is an umbrella rule for a set of metrics-based checks. Each metric-based
+check has its own rule name that starts from the common prefix
+@code{Metrics_}. For @option{+R} option, this name ends with @code{_GT}
+(greater then) or @code{_LT} (less then). The parameter of the rule
+@option{+R} option specifies bound (upper or lower, depending on the metric)
+for the given metric. A construct is flagged if a specified metric can be
+computed for it, and the resulting value is higher then the upper bound (or
+less than the lower bound) specified. Parameters and metric names are not
+case-sensitive @option{-R} option does not have a parameter and it turns OFF
+the check for the metric indicated by the metric rule name.
+
+The following table shows the available metrics-based checks, including the
+constraint that must be satisfied by the bound that is specified for the check
+and what bound - upper (U) or lower (L) - should be specified.
+
+@multitable {@code{Cyclomatic_Complexity}}{Cyclomatic complexity}{Positive integer}
+@ifnothtml
+@headitem Check Name @tab Description @tab Bounds Value
+@end ifnothtml
+@ifhtml
+@item @b{Check Name} @tab @b{Description} @tab @b{Bounds Value}
+@end ifhtml
+@c Above conditional code is workaround to bug in texi2html (Feb 2008)
+@item @code{Essential_Complexity} @tab Essential complexity @tab Positive integer (U)
+@item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer (U)
+@item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer (U)
+@end multitable
+
+@noindent
+The meaning and the computed values for all these metrics are exactly
+the same as for the corresponding metrics in @command{gnatmetric}.
+
+@emph{Example:} the rule
+@smallexample
++RMetrics_Cyclomatic_Complexity_GT : 7
+@end smallexample
+@noindent
+means that all bodies with cyclomatic complexity exceeding 7 will be flagged.
+
+To turn OFF the check for cyclomatic complexity metric, use the following option:
+@smallexample
+-RMetrics_Cyclomatic_Complexity
+@end smallexample
@node Misnamed_Identifiers
@subsection @code{Misnamed_Identifiers}
@itemize @bullet
@item
- type declarations
+type declarations
@item
- constant declarations (but not number declarations)
+constant declarations (but not number declarations)
@item
- package renaming declarations (but not generic package renaming
- declarations)
+package renaming declarations (but not generic package renaming
+declarations)
@end itemize
@noindent
@itemize @bullet
@item
- type-defining names end with @code{_T}, unless the type is an access type,
- in which case the suffix must be @code{_A}
+type-defining names end with @code{_T}, unless the type is an access type,
+in which case the suffix must be @code{_A}
@item
- constant names end with @code{_C}
+constant names end with @code{_C}
@item
- names defining package renamings end with @code{_R}
+names defining package renamings end with @code{_R}
@end itemize
@noindent
@itemize @bullet
@item
- For an incomplete type declaration: if the corresponding full type
- declaration is available, the defining identifier from the full type
- declaration is checked, but the defining identifier from the incomplete type
- declaration is not; otherwise the defining identifier from the incomplete
- type declaration is checked against the suffix specified for type
- declarations.
+For an incomplete type declaration: if the corresponding full type
+declaration is available, the defining identifier from the full type
+declaration is checked, but the defining identifier from the incomplete type
+declaration is not; otherwise the defining identifier from the incomplete
+type declaration is checked against the suffix specified for type
+declarations.
@item
- For a private type declaration (including private extensions), the defining
- identifier from the private type declaration is checked against the type
- suffix (even if the corresponding full declaration is an access type
- declaration), and the defining identifier from the corresponding full type
- declaration is not checked.
+For a private type declaration (including private extensions), the defining
+identifier from the private type declaration is checked against the type
+suffix (even if the corresponding full declaration is an access type
+declaration), and the defining identifier from the corresponding full type
+declaration is not checked.
@end itemize
@noindent
@end itemize
@noindent
-The rule may have the following parameter for the @option{+R} option:
+The rule has the following parameter for the @option{+R} option:
@table @emph
@item N
@end table
@noindent
-If the parameter for the @option{+R} option is not a positive integer,
-the parameter is ignored and the rule is turned ON with the most recently
-specified maximal non-flagged nesting level.
+If the parameter for the @option{+R} option is not specified or
+if it is not a positive integer, @option{+R} option is ignored.
If more then one option is specified for the gnatcheck call, the later option and
new parameter override the previous one(s).
-A @option{+R} option with no parameter turns the rule ON using the maximal
-non-flagged nesting level specified by the most recent @option{+R} option with
-a parameter, or the value 4 if there is no such previous @option{+R} option.
-
-
@node Parameters_Out_Of_Order
@subsection @code{Parameters_Out_Of_Order}
This rule has no parameters.
+@node Separate_Numeric_Error_Handlers
+@subsection @code{Separate_Numeric_Error_Handlers}
+@cindex @code{Separate_Numeric_Error_Handlers} rule (for @command{gnatcheck})
+
+@noindent
+Flags each exception handler that contains a choice for
+the predefined @code{Constraint_Error} exception, but does not contain
+the choice for the predefined @code{Numeric_Error} exception, or
+that contains the choice for @code{Numeric_Error}, but does not contain the
+choice for @code{Constraint_Error}.
+
+This rule has no parameters.
@ignore
@node Recursion
@command{gnatstub} has the command-line interface of the form
@smallexample
-$ gnatstub [switches] filename [directory]
+$ gnatstub @ovar{switches} @var{filename} @ovar{directory}
@end smallexample
@noindent
where
-@table @emph
+@table @var
@item filename
is the name of the source file that contains a library unit declaration
for which a body must be created. The file name may contain the path
@cindex @option{^-hg^/HEADER=GENERAL^} (@command{gnatstub})
Put a sample comment header into the body stub.
+@item ^--header-file=@var{filename}^/FROM_HEADER_FILE=@var{filename}^
+@cindex @option{^--header-file^/FROM_HEADER_FILE=^} (@command{gnatstub})
+Use the content of the file as the comment header for a generated body stub.
+
@ifclear vms
@item -IDIR
@cindex @option{-IDIR} (@command{gnatstub})
The command line is as follow:
@smallexample
-$ perl gnathtml.pl [^switches^options^] ada-files
+$ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files}
@end smallexample
@noindent
Alternatively, you may run the script using the following command line:
@smallexample
-$ perl gnathtml.pl [switches] files
+$ perl gnathtml.pl @ovar{switches} @var{files}
@end smallexample
@ifset vms
@noindent
@end ifset
+@ifclear vms
+@c ******************************
+@node Code Coverage and Profiling
+@chapter Code Coverage and Profiling
+@cindex Code Coverage
+@cindex Profiling
+
+@noindent
+This chapter describes how to use @code{gcov} - coverage testing tool - and
+@code{gprof} - profiler tool - on your Ada programs.
+
+@menu
+* Code Coverage of Ada Programs using gcov::
+* Profiling an Ada Program using gprof::
+@end menu
+
+@node Code Coverage of Ada Programs using gcov
+@section Code Coverage of Ada Programs using gcov
+@cindex gcov
+@cindex -fprofile-arcs
+@cindex -ftest-coverage
+@cindex -coverage
+@cindex Code Coverage
+
+@noindent
+@code{gcov} is a test coverage program: it analyzes the execution of a given
+program on selected tests, to help you determine the portions of the program
+that are still untested.
+
+@code{gcov} is part of the GCC suite, and is described in detail in the GCC
+User's Guide. You can refer to this documentation for a more complete
+description.
+
+This chapter provides a quick startup guide, and
+details some Gnat-specific features.
+
+@menu
+* Quick startup guide::
+* Gnat specifics::
+@end menu
+
+@node Quick startup guide
+@subsection Quick startup guide
+
+In order to perform coverage analysis of a program using @code{gcov}, 3
+steps are needed:
+
+@itemize @bullet
+@item
+Code instrumentation during the compilation process
+@item
+Execution of the instrumented program
+@item
+Execution of the @code{gcov} tool to generate the result.
+@end itemize
+
+The code instrumentation needed by gcov is created at the object level:
+The source code is not modified in any way, because the instrumentation code is
+inserted by gcc during the compilation process. To compile your code with code
+coverage activated, you need to recompile your whole project using the
+switches
+@code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using
+@code{-fprofile-arcs}.
+
+@smallexample
+$ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \
+ -largs -fprofile-arcs
+@end smallexample
+
+This compilation process will create @file{.gcno} files together with
+the usual object files.
+
+Once the program is compiled with coverage instrumentation, you can
+run it as many times as needed - on portions of a test suite for
+example. The first execution will produce @file{.gcda} files at the
+same location as the @file{.gcno} files. The following executions
+will update those files, so that a cumulative result of the covered
+portions of the program is generated.
+
+Finally, you need to call the @code{gcov} tool. The different options of
+@code{gcov} are available in the GCC User's Guide, section 'Invoking gcov'.
+
+This will create annotated source files with a @file{.gcov} extension:
+@file{my_main.adb} file will be analysed in @file{my_main.adb.gcov}.
+
+@node Gnat specifics
+@subsection Gnat specifics
+
+Because Ada semantics, portions of the source code may be shared among
+several object files. This is the case for example when generics are
+involved, when inlining is active or when declarations generate initialisation
+calls. In order to take
+into account this shared code, you need to call @code{gcov} on all
+source files of the tested program at once.
+
+The list of source files might exceed the system's maximum command line
+length. In order to bypass this limitation, a new mechanism has been
+implemented in @code{gcov}: you can now list all your project's files into a
+text file, and provide this file to gcov as a parameter, preceded by a @@
+(e.g. @samp{gcov @@mysrclist.txt}).
+
+@node Profiling an Ada Program using gprof
+@section Profiling an Ada Program using gprof
+@cindex gprof
+@cindex -pg
+@cindex Profiling
+
+@noindent
+This section is not meant to be an exhaustive documentation of @code{gprof}.
+Full documentation for it can be found in the GNU Profiler User's Guide
+documentation that is part of this GNAT distribution.
+
+Profiling a program helps determine the parts of a program that are executed
+most often, and are therefore the most time-consuming.
+
+@code{gprof} is the standard GNU profiling tool; it has been enhanced to
+better handle Ada programs and multitasking.
+It is currently supported on the following platforms
+@itemize @bullet
+@item
+linux x86/x86_64
+@item
+solaris sparc/sparc64/x86
+@item
+windows x86
+@end itemize
+
+@noindent
+In order to profile a program using @code{gprof}, 3 steps are needed:
+
+@itemize @bullet
+@item
+Code instrumentation, requiring a full recompilation of the project with the
+proper switches.
+@item
+Execution of the program under the analysis conditions, i.e. with the desired
+input.
+@item
+Analysis of the results using the @code{gprof} tool.
+@end itemize
+
+@noindent
+The following sections detail the different steps, and indicate how
+to interpret the results:
+@menu
+* Compilation for profiling::
+* Program execution::
+* Running gprof::
+* Interpretation of profiling results::
+@end menu
+
+@node Compilation for profiling
+@subsection Compilation for profiling
+@cindex -pg
+@cindex Profiling
+
+In order to profile a program the first step is to tell the compiler
+to generate the necessary profiling information. The compiler switch to be used
+is @code{-pg}, which must be added to other compilation switches. This
+switch needs to be specified both during compilation and link stages, and can
+be specified once when using gnatmake:
+
+@smallexample
+gnatmake -f -pg -P my_project
+@end smallexample
+
+@noindent
+Note that only the objects that were compiled with the @samp{-pg} switch will be
+profiled; if you need to profile your whole project, use the
+@samp{-f} gnatmake switch to force full recompilation.
+
+@node Program execution
+@subsection Program execution
+
+@noindent
+Once the program has been compiled for profiling, you can run it as usual.
+
+The only constraint imposed by profiling is that the program must terminate
+normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
+properly analyzed.
+
+Once the program completes execution, a data file called @file{gmon.out} is
+generated in the directory where the program was launched from. If this file
+already exists, it will be overwritten.
+
+@node Running gprof
+@subsection Running gprof
+
+@noindent
+The @code{gprof} tool is called as follow:
+
+@smallexample
+gprof my_prog gmon.out
+@end smallexample
+
+@noindent
+or simpler:
+
+@smallexample
+gprof my_prog
+@end smallexample
+
+@noindent
+The complete form of the gprof command line is the following:
+
+@smallexample
+gprof [^switches^options^] [executable [data-file]]
+@end smallexample
+
+@noindent
+@code{gprof} supports numerous ^switch^options^. The order of these
+^switch^options^ does not matter. The full list of options can be found in
+the GNU Profiler User's Guide documentation that comes with this documentation.
+
+The following is the subset of those switches that is most relevant:
+
+@table @option
+
+@item --demangle[=@var{style}]
+@itemx --no-demangle
+@cindex @option{--demangle} (@code{gprof})
+These options control whether symbol names should be demangled when
+printing output. The default is to demangle C++ symbols. The
+@code{--no-demangle} option may be used to turn off demangling. Different
+compilers have different mangling styles. The optional demangling style
+argument can be used to choose an appropriate demangling style for your
+compiler, in particular Ada symbols generated by GNAT can be demangled using
+@code{--demangle=gnat}.
+
+@item -e @var{function_name}
+@cindex @option{-e} (@code{gprof})
+The @samp{-e @var{function}} option tells @code{gprof} not to print
+information about the function @var{function_name} (and its
+children@dots{}) in the call graph. The function will still be listed
+as a child of any functions that call it, but its index number will be
+shown as @samp{[not printed]}. More than one @samp{-e} option may be
+given; only one @var{function_name} may be indicated with each @samp{-e}
+option.
+
+@item -E @var{function_name}
+@cindex @option{-E} (@code{gprof})
+The @code{-E @var{function}} option works like the @code{-e} option, but
+execution time spent in the function (and children who were not called from
+anywhere else), will not be used to compute the percentages-of-time for
+the call graph. More than one @samp{-E} option may be given; only one
+@var{function_name} may be indicated with each @samp{-E} option.
+
+@item -f @var{function_name}
+@cindex @option{-f} (@code{gprof})
+The @samp{-f @var{function}} option causes @code{gprof} to limit the
+call graph to the function @var{function_name} and its children (and
+their children@dots{}). More than one @samp{-f} option may be given;
+only one @var{function_name} may be indicated with each @samp{-f}
+option.
+
+@item -F @var{function_name}
+@cindex @option{-F} (@code{gprof})
+The @samp{-F @var{function}} option works like the @code{-f} option, but
+only time spent in the function and its children (and their
+children@dots{}) will be used to determine total-time and
+percentages-of-time for the call graph. More than one @samp{-F} option
+may be given; only one @var{function_name} may be indicated with each
+@samp{-F} option. The @samp{-F} option overrides the @samp{-E} option.
+
+@end table
+
+@node Interpretation of profiling results
+@subsection Interpretation of profiling results
+
+@noindent
+
+The results of the profiling analysis are represented by two arrays: the
+'flat profile' and the 'call graph'. Full documentation of those outputs
+can be found in the GNU Profiler User's Guide.
+
+The flat profile shows the time spent in each function of the program, and how
+many time it has been called. This allows you to locate easily the most
+time-consuming functions.
+
+The call graph shows, for each subprogram, the subprograms that call it,
+and the subprograms that it calls. It also provides an estimate of the time
+spent in each of those callers/called subprograms.
+@end ifclear
+
+@c ******************************
@node Running and Debugging Ada Programs
@chapter Running and Debugging Ada Programs
@cindex Debugging
@item
@findex GNAT
Files with prefix @file{^g-^G-^} are children of @code{GNAT}. These are useful
-general-purpose packages, fully documented in their specifications. All
+general-purpose packages, fully documented in their specs. All
the other @file{.c} files are modifications of common @command{gcc} files.
@end itemize
@cindex @code{Aux_DEC} package (child of @code{System})
These definitions are incorporated directly into package @code{System},
as though they had been declared there. For a
-list of the declarations added, see the specification of this package,
+list of the declarations added, see the spec of this package,
which can be found in the file @file{s-auxdec.ads} in the GNAT library.
@cindex @file{s-auxdec.ads} file
The pragma @code{Extend_System} is a configuration pragma, which means that
@noindent
HP Ada provides a specific version of the package
@code{SYSTEM} for each platform on which the language is implemented.
-For the complete specification of the package @code{SYSTEM}, see
+For the complete spec of the package @code{SYSTEM}, see
Appendix F of the @cite{HP Ada Language Reference Manual}.
On HP Ada, the package @code{SYSTEM} includes the following conversion
@item @code{TO_UNSIGNED_LONGWORD(ADDRESS)}
@item Function @code{IMPORT_VALUE return UNSIGNED_LONGWORD} and the
- functions @code{IMPORT_ADDRESS} and @code{IMPORT_LARGEST_VALUE}
+functions @code{IMPORT_ADDRESS} and @code{IMPORT_LARGEST_VALUE}
@end itemize
@noindent
@itemize @bullet
@item @code{TASK_INFO}
- This pragma appears within a task definition and
- applies to the task in which it appears. The argument
- must be of type @code{SYSTEM.TASK_INFO.TASK_INFO_TYPE}.
+This pragma appears within a task definition and
+applies to the task in which it appears. The argument
+must be of type @code{SYSTEM.TASK_INFO.TASK_INFO_TYPE}.
@item @code{TASK_STORAGE}
- GNAT implements pragma @code{TASK_STORAGE} in the same way as
- HP Ada.
- Both HP Ada and GNAT supply the pragmas @code{PASSIVE},
- @code{SUPPRESS}, and @code{VOLATILE}.
+GNAT implements pragma @code{TASK_STORAGE} in the same way as HP Ada.
+Both HP Ada and GNAT supply the pragmas @code{PASSIVE},
+@code{SUPPRESS}, and @code{VOLATILE}.
@end itemize
@node Scheduling and Task Priority
@subsection Scheduling and Task Priority
@item Adding the proper notation to generic formal parameters
that take unconstrained types in instantiation
-@item Adding pragma @code{ELABORATE_BODY} to package specifications
+@item Adding pragma @code{ELABORATE_BODY} to package specs
that have package bodies not otherwise allowed
@item Replacing occurrences of the identifier ``@code{PROTECTED}'' by
following conditions:
@itemize @bullet
@item Procedure with no formal parameters (returns @code{0} upon
- normal completion)
+normal completion)
@item Procedure with no formal parameters (returns @code{42} when
- an unhandled exception is raised)
+an unhandled exception is raised)
@item Function with no formal parameters whose returned value
- is of a discrete type
+is of a discrete type
@item Procedure with one @code{out} formal of a discrete type for
- which a specification of pragma @code{EXPORT_VALUED_PROCEDURE}
- is given.
+which a specification of pragma @code{EXPORT_VALUED_PROCEDURE} is given.
@end itemize
@item @option{/COMMAND}
-@item @option{/[NO]MAP}
+@item @option{/@r{[}NO@r{]}MAP}
-@item @option{/OUTPUT=@i{file-spec}}
+@item @option{/OUTPUT=@var{file-spec}}
-@item @option{/[NO]DEBUG} and @option{/[NO]TRACEBACK}
+@item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK}
@end itemize
@noindent
switches:
@itemize @bullet
-@item @option{/EXECUTABLE=@i{exec-name}}
+@item @option{/EXECUTABLE=@var{exec-name}}
@item @option{/VERBOSE}
-@item @option{/[NO]DEBUG} and @option{/[NO]TRACEBACK}
+@item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK}
@end itemize
@noindent
@item @command{ACS ENTER FOREIGN}
@tab Copy (*)@*
Allows the import of a foreign body as an Ada library
-specification and enters a reference to a pointer.
+spec and enters a reference to a pointer.
@item @command{ACS ENTER UNIT}
@tab Copy (*)@*
@sp 1
@item In a subprogram or entry declaration, maximum number of
- formal parameters that are of an unconstrained record type
+formal parameters that are of an unconstrained record type
@tab 32
@tab No set limit
@sp 1
@sp 1
@item Maximum number of formal parameters in an entry or
- subprogram declaration
+subprogram declaration
@tab 246
@tab No set limit
@sp 1
@sp 1
@item Maximum number of objects declared with the pragma @code{COMMON_OBJECT}
- or @code{PSECT_OBJECT}
+or @code{PSECT_OBJECT}
@tab 32757
@tab No set limit
@sp 1
@item Maximum number of enumeration literals in an enumeration type
- definition
+definition
@tab 65535
@tab No set limit
@sp 1
@c @multitable @columnfractions .3 .4 .4
@multitable {Source Code Analyzer /}{Tool with HP Ada}{Tool with GNAT Pro}
@item @i{Tool}
- @tab @i{Tool with HP Ada}
- @tab @i{Tool with @value{EDITION}}
+@tab @i{Tool with HP Ada}
+@tab @i{Tool with @value{EDITION}}
@item Code Management@*System
- @tab HP CMS
- @tab HP CMS
+@tab HP CMS
+@tab HP CMS
@item Language-Sensitive@*Editor
- @tab HP LSE
- @tab emacs or HP LSE (Alpha)
+@tab HP LSE
+@tab emacs or HP LSE (Alpha)
@item
- @tab
- @tab HP LSE (I64)
+@tab
+@tab HP LSE (I64)
@item Debugger
- @tab OpenVMS Debug
- @tab gdb (Alpha),
+@tab OpenVMS Debug
+@tab gdb (Alpha),
@item
- @tab
- @tab OpenVMS Debug (I64)
+@tab
+@tab OpenVMS Debug (I64)
@item Source Code Analyzer /@*Cross Referencer
- @tab HP SCA
- @tab GNAT XREF
+@tab HP SCA
+@tab GNAT XREF
@item Test Manager
- @tab HP Digital Test@*Manager (DTM)
- @tab HP DTM
+@tab HP Digital Test@*Manager (DTM)
+@tab HP DTM
@item Performance and@*Coverage Analyzer
- @tab HP PCA
- @tab HP PCA
+@tab HP PCA
+@tab HP PCA
@item Module Management@*System
- @tab HP MMS
- @tab Not applicable
+@tab HP MMS
+@tab Not applicable
@end multitable
@end flushleft
@end ifnottex
* Solaris-Specific Considerations::
* Linux-Specific Considerations::
* AIX-Specific Considerations::
+* Irix-Specific Considerations::
+* RTX-Specific Considerations::
@end menu
@node Summary of Run-Time Configurations
@item @code{@ @ @ @ }Tasking @tab native Win32 threads
@item @code{@ @ @ @ }Exceptions @tab SJLJ
@*
+@item @b{x86-windows-rtx}
+@item @code{@ @ }@i{rts-rtx-rtss (default)}
+@item @code{@ @ @ @ }Tasking @tab RTX real-time subsystem RTSS threads (kernel mode)
+@item @code{@ @ @ @ }Exceptions @tab SJLJ
+@*
+@item @code{@ @ }@i{rts-rtx-w32}
+@item @code{@ @ @ @ }Tasking @tab RTX Win32 threads (user mode)
+@item @code{@ @ @ @ }Exceptions @tab ZCX
+@*
@item @b{x86_64-linux}
@item @code{@ @ }@i{rts-native (default)}
@item @code{@ @ @ @ }Tasking @tab pthread library
@table @code
@item -2
Use the default configuration (run the program on all
- available processors) - this is the same as having
- @code{GNAT_PROCESSOR} unset
+available processors) - this is the same as having @code{GNAT_PROCESSOR}
+unset
@item -1
Let the run-time implementation choose one processor and run the program on
- that processor
+that processor
@item 0 .. Last_Proc
Run the program on the specified processor.
- @code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1}
+@code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1}
(where @code{_SC_NPROCESSORS_CONF} is a system variable).
@end table
specify a sufficiently large size for the stack of the task that contains
this call.
+@node Irix-Specific Considerations
+@section Irix-Specific Considerations
+@cindex Irix libraries
+
+@noindent
+The GCC support libraries coming with the Irix compiler have moved to
+their canonical place with respect to the general Irix ABI related
+conventions. Running applications built with the default shared GNAT
+run-time now requires the LD_LIBRARY_PATH environment variable to
+include this location. A possible way to achieve this is to issue the
+following command line on a bash prompt:
+
+@smallexample
+@group
+$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`dirname \`gcc --print-file-name=libgcc_s.so\``
+@end group
+@end smallexample
+
+@node RTX-Specific Considerations
+@section RTX-Specific Considerations
+@cindex RTX libraries
+
+@noindent
+The Real-time Extension (RTX) to Windows is based on the Windows Win32
+API. Applications can be built to work in two different modes:
+
+@itemize @bullet
+@item
+Windows executables that run in Ring 3 to utilize memory protection
+(@emph{rts-rtx-w32}).
+
+@item
+Real-time subsystem (RTSS) executables that run in Ring 0, where
+performance can be optimized with RTSS applications taking precedent
+over all Windows applications (@emph{rts-rtx-rtss}).
+
+@end itemize
+
@c *******************************
@node Example of Binder Output File
@appendix Example of Binder Output File
-- a-except.ads/adb for full details of how zero cost
-- exception handling works. This procedure, the call to
-- it, and the two following tables are all omitted if the
- -- build is in longjmp/setjump exception mode.
+ -- build is in longjmp/setjmp exception mode.
@findex SDP_Table_Build
@findex Zero Cost Exceptions
-- Call SDP_Table_Build to build the top level procedure
-- table for zero cost exception handling (omitted in
- -- longjmp/setjump mode).
+ -- longjmp/setjmp mode).
SDP_Table_Build (ST'Address, 23, EA'Address, 23);
@end smallexample
Compile the program with both optimization (@option{-O2}) and inlining
-enabled (@option{-gnatpn} instead of @option{-gnatp}).
+(@option{-gnatn}) enabled.
The @code{Incr} function is still compiled as usual, but at the
point in @code{Increment} where our function used to be called:
this in Ada 95 or Ada 2005:
@enumerate
@item
-If the source code for the libraries (specifications and bodies) are
+If the source code for the libraries (specs and bodies) are
available, then the libraries can be migrated in the same way as the
application.
@item
-If the source code for the specifications but not the bodies are
+If the source code for the specs but not the bodies are
available, then you can reimplement the bodies.
@item
Some features introduced by Ada 95 obviate the need for library support. For
All code that comes as part of GNAT is 64-bit clean, but the
restrictions given in @ref{Restrictions on use of 64 bit objects},
still apply. Look at the package
-specifications to see in which contexts objects allocated
+specs to see in which contexts objects allocated
in 64-bit address space are acceptable.
@node Technical details
caller) is in charge of cleaning the stack on routine exit. In addition,
the name of a routine with @code{Stdcall} calling convention is mangled by
adding a leading underscore (as for the @code{C} calling convention) and a
-trailing @code{@@}@code{@i{nn}}, where @i{nn} is the overall size (in
+trailing @code{@@}@code{@var{nn}}, where @var{nn} is the overall size (in
bytes) of the parameters passed to the routine.
The name to use on the Ada side when importing a C routine with a
@code{Stdcall} calling convention is the name of the C routine. The leading
-underscore and trailing @code{@@}@code{@i{nn}} are added automatically by
+underscore and trailing @code{@@}@code{@var{nn}} are added automatically by
the compiler. For instance the Win32 function:
@smallexample
@noindent
then the imported routine is @code{retrieve_val}, that is, there is no
decoration at all. No leading underscore and no Stdcall suffix
-@code{@@}@code{@i{nn}}.
+@code{@@}@code{@var{nn}}.
@noindent
This is especially important as in some special cases a DLL's entry
-point name lacks a trailing @code{@@}@code{@i{nn}} while the exported
+point name lacks a trailing @code{@@}@code{@var{nn}} while the exported
name generated for a call has it.
@noindent
@smallexample
@group
@cartouche
-[LIBRARY @i{name}]
-[DESCRIPTION @i{string}]
+@r{[}LIBRARY @var{name}@r{]}
+@r{[}DESCRIPTION @var{string}@r{]}
EXPORTS
- @i{symbol1}
- @i{symbol2}
+ @var{symbol1}
+ @var{symbol2}
@dots{}
@end cartouche
@end group
@end smallexample
@table @code
-@item LIBRARY @i{name}
+@item LIBRARY @var{name}
This section, which is optional, gives the name of the DLL.
-@item DESCRIPTION @i{string}
+@item DESCRIPTION @var{string}
This section, which is optional, gives a description string that will be
embedded in the import library.
@end table
@noindent
-Note that you must specify the correct suffix (@code{@@}@code{@i{nn}})
+Note that you must specify the correct suffix (@code{@@}@code{@var{nn}})
(@pxref{Windows Calling Conventions}) for a Stdcall
calling convention function in the exported symbols list.
@code{dll2def} is a very simple tool: it takes as input a DLL and prints
to standard output the list of entry points in the DLL. Note that if
some routines in the DLL have the @code{Stdcall} convention
-(@pxref{Windows Calling Conventions}) with stripped @code{@@}@i{nn}
+(@pxref{Windows Calling Conventions}) with stripped @code{@@}@var{nn}
suffix then you'll have to edit @file{api.def} to add it, and specify
@option{-k} to @command{gnatdll} when creating the import library.
@noindent
-Here are some hints to find the right @code{@@}@i{nn} suffix.
+Here are some hints to find the right @code{@@}@var{nn} suffix.
@enumerate
@item
name of the DLL containing the services listed in the definition file
@file{API.dll}. The name of the static import library generated is
computed from the name of the definition file as follows: if the
-definition file name is @i{xyz}@code{.def}, the import library name will
-be @code{lib}@i{xyz}@code{.a}. Note that in the previous example option
+definition file name is @var{xyz}@code{.def}, the import library name will
+be @code{lib}@var{xyz}@code{.a}. Note that in the previous example option
@option{-e} could have been removed because the name of the definition
file (before the ``@code{.def}'' suffix) is the same as the name of the
DLL (@pxref{Using gnatdll} for more information about @code{gnatdll}).
@smallexample
@cartouche
-$ gnatdll [@var{switches}] @var{list-of-files} [-largs @var{opts}]
+$ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
@end cartouche
@end smallexample
@noindent
-where @i{list-of-files} is a list of ALI and object files. The object
+where @var{list-of-files} is a list of ALI and object files. The object
file list must be the exact list of objects corresponding to the non-Ada
sources whose services are to be included in the DLL. The ALI file list
must be the exact list of ALI files for the corresponding Ada sources
-whose services are to be included in the DLL. If @i{list-of-files} is
+whose services are to be included in the DLL. If @var{list-of-files} is
missing, only the static import library is generated.
@noindent
You may specify any of the following switches to @code{gnatdll}:
@table @code
-@item -a[@var{address}]
+@item -a@ovar{address}
@cindex @option{-a} (@code{gnatdll})
Build a non-relocatable DLL at @var{address}. If @var{address} is not
specified the default address @var{0x11000000} will be used. By default,
@item -k
@cindex @option{-k} (@code{gnatdll})
-Removes the @code{@@}@i{nn} suffix from the import library's exported
+Removes the @code{@@}@var{nn} suffix from the import library's exported
names, but keeps them for the link names. You must specify this
option if you want to use a @code{Stdcall} function in a DLL for which
-the @code{@@}@i{nn} suffix has been removed. This is the case for most
+the @code{@@}@var{nn} suffix has been removed. This is the case for most
of the Windows NT DLL for example. This option has no effect when
@option{-n} option is specified.
is
@smallexample
-$ dlltool [@var{switches}]
+$ dlltool @ovar{switches}
@end smallexample
@noindent
@item -k
@cindex @option{-k} (@command{dlltool})
-Kill @code{@@}@i{nn} from exported names
+Kill @code{@@}@var{nn} from exported names
(@pxref{Windows Calling Conventions}
for a discussion about @code{Stdcall}-style symbols.
Generate an export file @var{exportfile}. The export file contains the
export table (list of symbols in the DLL) and is used to create the DLL.
-@item --output-lib @i{libfile}
+@item --output-lib @var{libfile}
@cindex @option{--output-lib} (@command{dlltool})
Generate a static import library @var{libfile}.
@cindex @option{-v} (@command{dlltool})
Verbose mode.
-@item --as @i{assembler-name}
+@item --as @var{assembler-name}
@cindex @option{--as} (@command{dlltool})
-Use @i{assembler-name} as the assembler. The default is @code{as}.
+Use @var{assembler-name} as the assembler. The default is @code{as}.
@end table
@node GNAT and Windows Resources
OSDN Git Service
