\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-2008, AdaCore o
-@c o
-@c GNAT is free software; you can redistribute it and/or modify it under o
-@c terms of the GNU General Public License as published by the Free Soft- o
-@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 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 (gnat_ugn) @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
* Stack Related Facilities::
* Verifying Properties Using gnatcheck::
* Creating Sample Bodies Using gnatstub::
+* Generating Ada Bindings for C and C++ headers::
* Other Utility Programs::
* Running and Debugging Ada Programs::
@ifclear vms
a utility that generates empty but compilable bodies for library units.
@item
+@ref{Generating Ada Bindings for C and C++ headers}, describes how to
+generate automatically Ada bindings from C and C++ headers.
+
+@item
@ref{Other Utility Programs}, discusses several other GNAT utilities,
including @code{gnathtml}.
@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.
-Note that
-@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary
-to specify both options.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@item
If an object file @file{O} depends on the proper body of a subunit through
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
@item -fno-inline-functions
@cindex @option{-fno-inline-functions} (@command{gcc})
-Suppresses automatic inlining of small subprograms, which is enabled
+Suppresses automatic inlining of simple subprograms, which is enabled
if @option{-O3} is used.
+@item -fno-inline-small-functions
+@cindex @option{-fno-inline-small-functions} (@command{gcc})
+Suppresses automatic inlining of small subprograms, which is enabled
+if @option{-O2} is used.
+
@item -fno-inline-functions-called-once
@cindex @option{-fno-inline-functions-called-once} (@command{gcc})
Suppresses inlining of subprograms local to the unit and called once
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
@cindex @option{-gnatb} (@command{gcc})
Generate brief messages to @file{stderr} even if verbose mode set.
+@item -gnatB
+@cindex @option{-gnatB} (@command{gcc})
+Assume no invalid (bad) values except for 'Valid attribute use.
+
@item -gnatc
@cindex @option{-gnatc} (@command{gcc})
Check syntax and semantics only (no code generation attempted).
programmers, and these are documented at appropriate points in this
users guide.
+@ifclear vms
@item -gnatD
-@cindex @option{-gnatD} (@command{gcc})
+@cindex @option{-gnatD[nn]} (@command{gcc})
+@end ifclear
+@ifset vms
+@item /XDEBUG /LXDEBUG=nnn
+@end ifset
Create expanded source files for source level debugging. This switch
also suppress generation of cross-reference information
(see @option{-gnatx}).
@end ifclear
(@pxref{The Configuration Pragmas Files}).
-@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
+@item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=@var{value}@r{]}
@cindex @option{-gnateD} (@command{gcc})
-Defines a symbol, associated with value, for preprocessing.
+Defines a symbol, associated with @var{value}, for preprocessing.
(@pxref{Integrated Preprocessing}).
@item -gnatef
@cindex @option{-gnatef} (@command{gcc})
Display full source path name in brief error messages.
+@item -gnateG
+@cindex @option{-gnateG} (@command{gcc})
+Save result of preprocessing in a text file.
+
@item -gnatem=@var{path}
@cindex @option{-gnatem} (@command{gcc})
Specify a mapping file
so that all standard warnings and all standard style options are turned on.
All warnings and style error messages are treated as errors.
-@item -gnatG
-@cindex @option{-gnatG} (@command{gcc})
+@ifclear vms
+@item -gnatG=nn
+@cindex @option{-gnatG[nn]} (@command{gcc})
+@end ifclear
+@ifset vms
+@item /EXPAND_SOURCE, /LEXPAND_SOURCE=nnn
+@end ifset
List generated expanded code in source form.
@item ^-gnath^/HELP^
@item -gnatm=@var{n}
@cindex @option{-gnatm} (@command{gcc})
Limit number of detected error or warning messages to @var{n}
-where @var{n} is in the range 1..999_999. The default setting if
-no switch is given is 9999. Compilation is terminated if this
-limit is exceeded. The equal sign here is optional.
+where @var{n} is in the range 1..999999. The default setting if
+no switch is given is 9999. If the number of warnings reaches this
+limit, then a message is output and further warnings are suppressed,
+but the compilation is continued. If the number of error messages
+reaches this limit, then a message is output and the compilation
+is abandoned. The equal sign here is optional. A value of zero
+means that no limit applies.
@item -gnatn
@cindex @option{-gnatn} (@command{gcc})
pragma @code{Inline} is specified. This inlining is performed
by the front end and will be visible in the
@option{-gnatG} output.
-In some cases, this has proved more effective than the back end
-inlining resulting from the use of
-@option{-gnatn}.
-Note that
-@option{-gnatN} automatically implies
-@option{-gnatn} so it is not necessary
-to specify both options. There are a few cases that the back-end inlining
-catches that cannot be dealt with in the front-end.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@item -gnato
@cindex @option{-gnato} (@command{gcc})
Enable numeric overflow checking (which is not normally enabled by
-default). Not that division by zero is a separate check that is not
+default). Note that division by zero is a separate check that is not
controlled by this switch (division by zero checking is on by default).
@item -gnatp
@cindex @option{-gnatp} (@command{gcc})
-Suppress all checks.
+Suppress all checks. See @ref{Run-Time Checks} for details.
@item -gnatP
@cindex @option{-gnatP} (@command{gcc})
@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:
The @code{m} stands for maximum.
@end ifclear
@var{n} is a decimal integer in the
-range of 1 to 999 and limits the number of error messages to be
-generated. For example, using @option{-gnatm2} might yield
+range of 1 to 999999 and limits the number of error or warning
+messages to be generated. For example, using
+@option{-gnatm2} might yield
@smallexample
e.adb:3:04: Incorrect spelling of keyword "function"
e.adb:5:35: missing ".."
-fatal error: maximum errors reached
+fatal error: maximum number of errors detected
compilation abandoned
@end smallexample
@noindent
+The default setting if
+no switch is given is 9999. If the number of warnings reaches this
+limit, then a message is output and further warnings are suppressed,
+but the compilation is continued. If the number of error messages
+reaches this limit, then a message is output and the compilation
+is abandoned. A value of zero means that no limit applies.
+
+@noindent
Note that the equal sign is optional, so the switches
@option{-gnatm2} and @option{-gnatm=2} are equivalent.
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})
@smallexample
@cartouche
- @b{pragma} Assert (@var{Boolean-expression} [,
- @var{static-string-expression}])
+ @b{pragma} Assert (@var{Boolean-expression} @r{[},
+ @var{static-string-expression}@r{]})
@b{pragma} Debug (@var{procedure call})
@end cartouche
@end smallexample
debugging procedures to be called between declarations.
@ifset vms
-@item /DEBUG[=debug-level]
+@item /DEBUG@r{[}=debug-level@r{]}
@itemx /NODEBUG
Specifies how much debugging information is to be included in
the resulting object file where 'debug-level' is one of the following:
and subscripts on the left hand side (where memory corruption could
occur as a result of an invalid value).
+The @option{-gnatB} switch tells the compiler to assume that all
+values are valid (that is, within their declared subtype range)
+except in the context of a use of the Valid attribute. This means
+the compiler can generate more efficient code, since the range
+of values is better known at compile time.
+
The @option{-gnatV^@var{x}^^} switch allows more control over the validity
checking mode.
@ifclear vms
the value of this suffix is used in the ordering (e.g.@: Junk2 comes
before Junk10).
+@item ^O^OVERRIDING_INDICATORS^
+@emph{Check that overriding subprograms are explicitly marked as such.}
+The declaration of a primitive operation of a type extension that overrides
+an inherited operation must carry an overriding indicator.
+
@item ^p^PRAGMA^
@emph{Check pragma casing.}
Pragma names must be written in mixed case, that is, the
@cindex Checks, stack overflow checking
@noindent
-If you compile with the default options, GNAT will insert many run-time
-checks into the compiled code, including code that performs range
-checking against constraints, but not arithmetic overflow checking for
-integer operations (including division by zero), checks for access
-before elaboration on subprogram calls, or stack overflow checking. All
-other run-time checks, as required by the Ada Reference Manual, are
-generated by default. The following @command{gcc} switches refine this
-default behavior:
+By default, the following checks are suppressed: integer overflow
+checks, stack overflow checks, and checks for access before
+elaboration on subprogram calls. All other checks, including range
+checks and array bounds checks, are turned on by default. The
+following @command{gcc} switches refine this default behavior.
@table @option
@c !sort!
@cindex Suppressing checks
@cindex Checks, suppressing
@findex Suppress
-Suppress all run-time checks as though @code{pragma Suppress (all_checks})
+Suppress all run-time checks as though @code{pragma Suppress (All_checks)}
had been present in the source. Validity checks are also suppressed (in
other words @option{-gnatp} also implies @option{-gnatVn}.
Use this switch to improve the performance
of the code at the expense of safety in the presence of invalid data or
program bugs.
+Note that when checks are suppressed, the compiler is allowed, but not
+required, to omit the checking code. If the run-time cost of the
+checking code is zero or near-zero, the compiler will generate it even
+if checks are suppressed. In particular, if the compiler can prove
+that a certain check will necessarily fail, it will generate code to
+do an unconditional ``raise'', even if checks are suppressed. The
+compiler warns in this case.
+
+Of course, run-time checks are omitted whenever the compiler can prove
+that they will not fail, whether or not checks are suppressed.
+
+Note that if you suppress a check that would have failed, program
+execution is erroneous, which means the behavior is totally
+unpredictable. The program might crash, or print wrong answers, or
+do anything else. It might even do exactly what you wanted it to do
+(and then it might start failing mysteriously next week or next
+year). The compiler will generate code based on the assumption that
+the condition being checked is true, which can result in disaster if
+that assumption is wrong.
+
@item -gnato
@cindex @option{-gnato} (@command{gcc})
@cindex Overflow checks
range of the result type. The following example shows the distinction:
@smallexample @c ada
-X1 : Integer := Integer'Last;
-X2 : Integer range 1 .. 5 := 5;
-X3 : Integer := Integer'Last;
-X4 : Integer range 1 .. 5 := 5;
-F : Float := 2.0E+20;
+X1 : Integer := "Integer'Last";
+X2 : Integer range 1 .. 5 := "5";
+X3 : Integer := "Integer'Last";
+X4 : Integer range 1 .. 5 := "5";
+F : Float := "2.0E+20";
@dots{}
X1 := X1 + 1;
X2 := X2 + 1;
@end smallexample
@noindent
+Note that if explicit values are assigned at compile time, the
+compiler may be able to detect overflow at compile time, in which case
+no actual run-time checking code is required, and Constraint_Error
+will be raised unconditionally, with or without
+@option{-gnato}. That's why the assigned values in the above fragment
+are in quotes, the meaning is "assign a value not known to the
+compiler that happens to be equal to ...". The remaining discussion
+assumes that the compiler cannot detect the values at compile time.
+
Here the first addition results in a value that is outside the base range
of Integer, and hence requires an overflow check for detection of the
constraint error. Thus the first assignment to @code{X1} raises a
@code{Constraint_Error} exception only if @option{-gnato} is set.
-The second increment operation results in a violation
-of the explicit range constraint, and such range checks are always
-performed (unless specifically suppressed with a pragma @code{suppress}
-or the use of @option{-gnatp}).
+The second increment operation results in a violation of the explicit
+range constraint; such range checks are performed by default, and are
+unaffected by @option{-gnato}.
The two conversions of @code{F} both result in values that are outside
the base range of type @code{Integer} and thus will raise
@cindex Check, elaboration
Enables dynamic checks for access-before-elaboration
on subprogram calls and generic instantiations.
+Note that @option{-gnatE} is not necessary for safety, because in the
+default mode, GNAT ensures statically that the checks would not fail.
For full details of the effect and use of this switch,
@xref{Compiling Using gcc}.
@item -gnatN
@cindex @option{-gnatN} (@command{gcc})
-The front end inlining activated by this switch is generally more extensive,
-and quite often more effective than the standard @option{-gnatn} inlining mode.
-It will also generate additional dependencies.
-Note that
-@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary
-to specify both options.
+This switch activates front-end inlining which also
+generates additional dependencies.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@end table
@node Auxiliary Output Control
file @file{debug.adb}.
@end ifclear
-@item -gnatG
+@item -gnatG[=nn]
@cindex @option{-gnatG} (@command{gcc})
This switch causes the compiler to generate auxiliary output containing
a pseudo-source listing of the generated expanded code. Like most Ada
these cases, and consider whether it may be desirable to modify the coding
approach to improve efficiency.
+The optional parameter @code{nn} if present after -gnatG specifies an
+alternative maximum line length that overrides the normal default of 72.
+This value is in the range 40-999999, values less than 40 being silently
+reset to 40. The equal sign is optional.
+
The format of the output is very similar to standard Ada source, and is
easily understood by an Ada programmer. The following special syntactic
additions correspond to low level features used in the generated code that
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.
evaluation of the expression 1.0/27.0).
@end table
-@item -gnatD
+@item -gnatD[=nn]
@cindex @option{-gnatD} (@command{gcc})
When used in conjunction with @option{-gnatG}, this switch causes
the expanded source, as described above for
@option{-gnatDG}, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
+The optional parameter @code{nn} if present after -gnatD specifies an
+alternative maximum line length that overrides the normal default of 72.
+This value is in the range 40-999999, values less than 40 being silently
+reset to 40. The equal sign is optional.
+
@item -gnatr
@cindex @option{-gnatr} (@command{gcc})
@cindex pragma Restrictions
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
-- list all symbols with their values.
@end smallexample
-@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
+@item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=value@r{]}
@cindex @option{-gnateD} (@command{gcc})
Define or redefine a preprocessing symbol, associated with value. If no value
is given on the command line, then the value of the symbol is @code{True}.
@noindent
This switch is similar to switch @option{^-D^/ASSOCIATE^} of @code{gnatprep}.
+@item -gnateG
+When integrated preprocessing is performed and the preprocessor modifies
+the source text, write the result of this preprocessing into a file
+<source>^.prep^_prep^.
+
@end table
@node Code Generation Control
The 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
@item ^-m^/ERROR_LIMIT=^@var{n}
@cindex @option{^-m^/ERROR_LIMIT^} (@command{gnatbind})
-Limit number of detected errors to @var{n}, where @var{n} is
-in the range 1..999_999. The default value if no switch is
-given is 9999. Binding is terminated if the limit is exceeded.
+Limit number of detected errors or warnings to @var{n}, where @var{n} is
+in the range 1..999999. The default value if no switch is
+given is 9999. If the number of warnings reaches this limit, then a
+message is output and further warnings are suppressed, the bind
+continues in this case. If the number of errors reaches this
+limit, then a message is output and the bind is abandoned.
+A value of zero means that no limit is enforced. The equal
+sign is optional.
+
@ifset unw
Furthermore, under Windows, the sources pointed to by the libraries path
set in the registry are not searched for.
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
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
@cindex @option{^-d^/DISPLAY_PROGRESS^} (@command{gnatmake})
Display progress for each source, up to date or not, as a single line
- completed x out of y (zz%)
+@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.
@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
@subsection Controlling Run-Time Checks
@noindent
-By default, GNAT generates all run-time checks, except arithmetic overflow
-checking for integer operations and checks for access before elaboration on
+By default, GNAT generates all run-time checks, except integer overflow
+checks, stack overflow checks, and checks for access before elaboration on
subprogram calls. The latter are not required in default mode, because all
necessary checking is done at compile time.
@cindex @option{-gnatp} (@command{gcc})
@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
time you compile, regarding the source files that it writes as temporary
files that you throw away.
+Note that if your file containing multiple units starts with a byte order
+mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop
+will each start with a copy of this BOM, meaning that they can be compiled
+automatically in UTF-8 mode without needing to specify an explicit encoding.
+
@node Operating gnatchop in Compilation Mode
@section Operating gnatchop in Compilation Mode
The @code{gnatchop} command has the form:
@smallexample
-$ gnatchop switches @var{file name} [@var{file name} @var{file name} @dots{}]
- [@var{directory}]
+$ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]}
+ @ovar{directory}
@end smallexample
@noindent
The usual form of the @code{gnatname} command is
@smallexample
-$ gnatname [@var{switches}] @var{naming_pattern} [@var{naming_patterns}] \
- [--and @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
@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
@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
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
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,
@ifclear vms
@smallexample
-$ gnatkr @var{name} [@var{length}]
+$ gnatkr @var{name} @ovar{length}
@end smallexample
@end ifclear
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.
@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
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} utility monitors dynamic allocation and
deallocation activity in a program, and displays information about
incorrect deallocations and possible sources of memory leaks.
-It provides three type of information:
+It is designed to work in association with a static runtime library
+only and in this context provides three types of information:
@itemize @bullet
@item
General information concerning memory management, such as the total
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::
of this construct in the generic unit to the place where this unit is
instantiated.
+@cindex @option{^-m^/DIAGNOSTIC_LIMIT^} (@command{gnatcheck})
+@item ^-m@i{nnn}^/DIAGNOSTIC_LIMIT=@i{nnn}^
+Maximum number of diagnoses to be sent to Stdout, @i{nnn} from o@dots{}1000,
+the default value is 500. Zero means that there is no limitation on
+the number of diagnostic messages to be printed into Stdout.
+
@cindex @option{^-q^/QUIET^} (@command{gnatcheck})
@item ^-q^/QUIET^
Quiet mode. All the diagnoses about rule violations are placed in the
Turn all the rule checks OFF.
@cindex @option{+R} (@command{gnatcheck})
-@item +R@i{rule_id[:param]}
+@item +R@var{rule_id}@r{[}:@var{param}@r{]}
Turn on the check for a specified rule with the specified parameter, if any.
-@i{rule_id} must be the identifier of one of the currently implemented rules
+@var{rule_id} must be the identifier of one of the currently implemented rules
(use @option{^-h^/HELP^} for the list of implemented rules). Rule identifiers
-are not case-sensitive. The @i{param} item must
+are not case-sensitive. The @var{param} item must
be a string representing a valid parameter(s) for the specified rule.
If it contains any space characters then this string must be enclosed in
quotation marks.
@cindex @option{-R} (@command{gnatcheck})
-@item -R@i{rule_id[:param]}
+@item -R@var{rule_id}@r{[}:@var{param}@r{]}
Turn off the check for a specified rule with the specified parameter, if any.
@cindex @option{-from} (@command{gnatcheck})
-@item -from=@i{rule_option_filename}
-Read the rule options from the text file @i{rule_option_filename}, referred as
+@item -from=@var{rule_option_filename}
+Read the rule options from the text file @var{rule_option_filename}, referred as
``rule file'' below.
@end table
@noindent
-The default behavior is that all the rule checks are enabled, except for
-the checks performed by the compiler.
-@ignore
-and the checks associated with the
-global rules.
-@end ignore
+The default behavior is that all the rule checks are disabled.
A rule file is a text file containing a set of rule options.
@cindex Rule file (for @code{gnatcheck})
lines and end-of-line comments). The rule file has free format; that is,
you do not have to start a new rule option on a new line.
-A rule file may contain other @option{-from=@i{rule_option_filename}}
+A rule file may contain other @option{-from=@var{rule_option_filename}}
options, each such option being replaced with the content of the
corresponding rule file during the rule files processing. In case a
-cycle is detected (that is, @i{rule_file_1} reads rule options from
-@i{rule_file_2}, and @i{rule_file_2} reads (directly or indirectly)
-rule options from @i{rule_file_1}), the processing
-of rule files is interrupted and a part of their content is ignored.
+cycle is detected (that is, @file{@var{rule_file_1}} reads rule options
+from @file{@var{rule_file_2}}, and @file{@var{rule_file_2}} reads
+(directly or indirectly) rule options from @file{@var{rule_file_1}}),
+the processing of rule files is interrupted and a part of their content
+is ignored.
@node Adding the Results of Compiler Checks to gnatcheck Output
@ignore
* Improperly_Called_Protected_Entries::
@end ignore
-* Metrics_Violation::
+* Metrics::
* Misnamed_Identifiers::
* Multiple_Entries_In_Protected_Definitions::
* Name_Clashes::
This rule has no parameters.
@end ignore
-@node Metrics_Violation
-@subsection @code{Metrics_Violation}
+@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. The parameters of
-the rule specify which metrics should be checked, and a bound (upper or lower,
-depending on the metric) for each specified 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.
-
-This rule has the following parameters:
+There is a set of checks based on computing a metric value and comparing the
+result with the specified upper (or lower, depending on a specific metric)
+value specified for a given metric. A construct is flagged if a given metric
+is applicable (can be computed) for it and the computed value is greater
+then (lover then) the specified upper (lower) bound.
-@itemize @bullet
-@item
-For the @option{+R} option:
-@table @code
-@item @i{Metric_Check_Name} < @i{LowerBound}
-Turns the check for the specified metric ON and specifies the lower bound
-for a given metric check
-
-@item @i{Metric_Check_Name} > @i{UpperBound}
+The name of any metric-based rule consists of the prefix @code{Metrics_}
+followed by the name of the corresponding metric (see the table below).
+For @option{+R} option, each metric-based rule has a numeric parameter
+specifying the bound (integer or real, depending on a metric), @option{-R}
+option for metric rules does not have a parameter.
-Turns the check for the specified metric ON and specifies the upper bound
-for a given metric check
-@end table
-
-@item
-For the @option{-R} option:
-@table @code
-@item @i{Metric_Check_Name}
-Turns the check for the specified metric OFF
-@end table
-@end itemize
-
-@noindent
-Parameters are not case-sensitive. @i{Metric_Check_Name} must be
-the name of a metric supported by the @code{Metrics_Violation} rule
-(see the table below),
-otherwise the parameter is ignored. Whether the upper or lower bound
-is specified for a given check, depends on the metric. If a
-parameter for the @option{+R} option specifies an invalid limit, a
-warning is issued and the parameter is ignored.
-
-The @option{-R} option without parameters turns OFF all the previously enabled
-metric checks. the @option{+R} option without parameters turns ON all the
-metric checks that have been defined by previous @option{+R} options with
-valid parameters. @option{+R} option with a valid
-parameter also turns ON all the other metric checks that have been defined
-by previous @option{+R} options with valid parameters if they have been
-disabled by @option{-R} option without parameters.
-
-By default no metrics checks are ON, so the @option{+R} option without
-parameters actually does not specify any check.
-
-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.
+The following table shows the metric names for that the corresponding
+metrics-based checks are supported by gnatcheck, including the
+constraint that must be satisfied by the bound that is specified for the check
+and what bound - upper (U) or lower (L) - should be specified.
@multitable {@code{Cyclomatic_Complexity}}{Cyclomatic complexity}{Positive integer}
@ifnothtml
@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
-@item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer
-@item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer
+@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
@emph{Example:} the rule
@smallexample
-+RMetrics_Violation: Cyclomatic_Complexity > 7
++RMetrics_Cyclomatic_Complexity : 7
@end smallexample
@noindent
means that all bodies with cyclomatic complexity exceeding 7 will be flagged.
+To turn OFF the check for cyclomatic complexity metric, use the following option:
+@smallexample
+-RMetrics_Cyclomatic_Complexity
+@end smallexample
+
@node Misnamed_Identifiers
@subsection @code{Misnamed_Identifiers}
@cindex @code{Misnamed_Identifiers} rule (for @command{gnatcheck})
@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}
the source search path when calling @command{gnatstub}, see the description
of @command{gnatstub} switches below.
+By default, all the program unit body stubs generated by @code{gnatstub}
+raise the predefined @code{Program_Error} exception, which will catch
+accidental calls of generated stubs. This behavior can be changed with
+option @option{^--no-exception^/NO_EXCEPTION^} (see below).
+
@menu
* Running gnatstub::
* Switches for gnatstub::
@command{gnatstub} has the command-line interface of the form
@smallexample
-$ gnatstub [switches] filename [directory]
+$ gnatstub @ovar{switches} @var{filename} @ovar{directory}
@end smallexample
@noindent
where
-@table @emph
+@table @var
@item filename
is the name of the source file that contains a library unit declaration
for which a body must be created. The file name may contain the path
@cindex @option{^-l^/LINE_LENGTH^} (@command{gnatstub})
Same as @option{^-gnatyM^/MAX_LINE_LENGTH=^@var{n}}
-@item ^-o^/BODY=^@var{body-name}
+@item ^--no-exception^/NO_EXCEPTION^
+@cindex @option{^--no-exception^/NO_EXCEPTION^} (@command{gnatstub})
+Avoind raising PROGRAM_ERROR in the generated bodies of program unit stubs.
+This is not always possible for function stubs.
+
+@item ^-o ^/BODY=^@var{body-name}
@cindex @option{^-o^/BODY^} (@command{gnatstub})
Body file name. This should be set if the argument file name does not
follow
@end table
+@c *********************************
+@node Generating Ada Bindings for C and C++ headers
+@chapter Generating Ada Bindings for C and C++ headers
+@findex binding
+
+@noindent
+GNAT now comes with a new experimental binding generator for C and C++
+headers which is intended to do 95% of the tedious work of generating
+Ada specs from C or C++ header files. Note that this still is a work in
+progress, not designed to generate 100% correct Ada specs.
+
+The code generated is using the Ada 2005 syntax, which makes it
+easier to interface with other languages than previous versions of Ada.
+
+@menu
+* Running the binding generator::
+* Generating bindings for C++ headers::
+* Switches::
+@end menu
+
+@node Running the binding generator
+@section Running the binding generator
+
+@noindent
+The binding generator is part of the @command{gcc} compiler and can be
+invoked via the @option{-fdump-ada-spec} switch, which will generate Ada
+spec files for the header files specified on the command line, and all
+header files needed by these files transitivitely. For example:
+
+@smallexample
+$ g++ -c -fdump-ada-spec -C /usr/include/time.h
+$ gcc -c -gnat05 *.ads
+@end smallexample
+
+will generate, under GNU/Linux, the following files: @file{time_h.ads},
+@file{bits_time_h.ads}, @file{stddef_h.ads}, @file{bits_types_h.ads} which
+correspond to the files @file{/usr/include/time.h},
+@file{/usr/include/bits/time.h}, etc@dots{}, and will then compile in Ada 2005
+mode these Ada specs.
+
+The @code{-C} switch tells @command{gcc} to extract comments from headers,
+and will attempt to generate corresponding Ada comments.
+
+If you want to generate a single Ada file and not the transitive closure, you
+can use instead the @option{-fdump-ada-spec-slim} switch.
+
+Note that we recommend when possible to use the @command{g++} driver to
+generate bindings, even for most C headers, since this will in general
+generate better Ada specs. For generating bindings for C++ headers, it is
+mandatory to use the @command{g++} command, or @command{gcc -x c++} which
+is equivalent in this case. If @command{g++} cannot work on your C headers
+because of incompatibilities between C and C++, then you can fallback to
+@command{gcc} instead.
+
+For an example of better bindings generated from the C++ front-end,
+the name of the parameters (when available) are actually ignored by the C
+front-end. Consider the following C header:
+
+@smallexample
+extern void foo (int variable);
+@end smallexample
+
+with the C front-end, @code{variable} is ignored, and the above is handled as:
+
+@smallexample
+extern void foo (int);
+@end smallexample
+
+generating a generic:
+
+@smallexample
+procedure foo (param1 : int);
+@end smallexample
+
+with the C++ front-end, the name is available, and we generate:
+
+@smallexample
+procedure foo (variable : int);
+@end smallexample
+
+In some cases, the generated bindings will be more complete or more meaningful
+when defining some macros, which you can do via the @option{-D} switch. This
+is for example the case with @file{Xlib.h} under GNU/Linux:
+
+@smallexample
+g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
+@end smallexample
+
+The above will generate more complete bindings than a straight call without
+the @option{-DXLIB_ILLEGAL_ACCESS} switch.
+
+In other cases, it is not possible to parse a header file in a stand alone
+manner, because other include files need to be included first. In this
+case, the solution is to create a small header file including the needed
+@code{#include} and possible @code{#define} directives. For example, to
+generate Ada bindings for @file{readline/readline.h}, you need to first
+include @file{stdio.h}, so you can create a file with the following two
+lines in e.g. @file{readline1.h}:
+
+@smallexample
+#include <stdio.h>
+#include <readline/readline.h>
+@end smallexample
+
+and then generate Ada bindings from this file:
+
+@smallexample
+$ g++ -c -fdump-ada-spec readline1.h
+@end smallexample
+
+@node Generating bindings for C++ headers
+@section Generating bindings for C++ headers
+
+@noindent
+Generating bindings for C++ headers is done using the same options, always
+with the @command{g++} compiler.
+
+In this mode, C++ classes will be mapped to Ada tagged types, constructors
+will be mapped using the @code{CPP_Constructor} pragma, and when possible,
+multiple inheritance of abstract classes will be mapped to Ada interfaces
+(@xref{Interfacing to C++,,,gnat_rm, GNAT Reference Manual}, for additional
+information on interfacing to C++).
+
+For example, given the following C++ header file:
+
+@smallexample
+@group
+@cartouche
+class Carnivore @{
+public:
+ virtual int Number_Of_Teeth () = 0;
+@};
+
+class Domestic @{
+public:
+ virtual void Set_Owner (char* Name) = 0;
+@};
+
+class Animal @{
+public:
+ int Age_Count;
+ virtual void Set_Age (int New_Age);
+@};
+
+class Dog : Animal, Carnivore, Domestic @{
+ public:
+ int Tooth_Count;
+ char *Owner;
+
+ virtual int Number_Of_Teeth ();
+ virtual void Set_Owner (char* Name);
+
+ Dog();
+@};
+@end cartouche
+@end group
+@end smallexample
+
+The corresponding Ada code is generated:
+
+@smallexample @c ada
+@group
+@cartouche
+ package Class_Carnivore is
+ type Carnivore is limited interface;
+ pragma Import (CPP, Carnivore);
+
+ function Number_Of_Teeth (this : access Carnivore) return int is abstract;
+ end;
+ use Class_Carnivore;
+
+ package Class_Domestic is
+ type Domestic is limited interface;
+ pragma Import (CPP, Domestic);
+
+ procedure Set_Owner
+ (this : access Domestic;
+ Name : Interfaces.C.Strings.chars_ptr) is abstract;
+ end;
+ use Class_Domestic;
+
+ package Class_Animal is
+ type Animal is tagged limited record
+ Age_Count : aliased int;
+ end record;
+ pragma Import (CPP, Animal);
+
+ procedure Set_Age (this : access Animal; New_Age : int);
+ pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi");
+ end;
+ use Class_Animal;
+
+ package Class_Dog is
+ type Dog is new Animal and Carnivore and Domestic with record
+ Tooth_Count : aliased int;
+ Owner : Interfaces.C.Strings.chars_ptr;
+ end record;
+ pragma Import (CPP, Dog);
+
+ function Number_Of_Teeth (this : access Dog) return int;
+ pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv");
+
+ procedure Set_Owner
+ (this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
+ pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");
+
+ function New_Dog return Dog'Class;
+ pragma CPP_Constructor (New_Dog);
+ pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
+ end;
+ use Class_Dog;
+@end cartouche
+@end group
+@end smallexample
+
+@node Switches
+@section Switches
+
+@table @option
+@item -fdump-ada-spec
+@cindex @option{-fdump-ada-spec} (@command{gcc})
+Generate Ada spec files for the given header files transitively (including
+all header files that these headers depend upon).
+
+@item -fdump-ada-spec-slim
+@cindex @option{-fdump-ada-spec-slim} (@command{gcc})
+Generate Ada spec files for the header files specified on the command line
+only.
+
+@item -C
+@cindex @option{-C} (@command{gcc})
+Extract comments from headers and generate Ada comments in the Ada spec files.
+@end table
+
@node Other Utility Programs
@chapter Other Utility Programs
The command line is as follow:
@smallexample
-$ perl gnathtml.pl [^switches^options^] ada-files
+$ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files}
@end smallexample
@noindent
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
text file, and provide this file to gcov as a parameter, preceded by a @@
(e.g. @samp{gcov @@mysrclist.txt}).
+Note that on AIX compiling a static library with @code{-fprofile-arcs} is
+not supported as there can be unresolved symbols during the final link.
+
@node Profiling an Ada Program using gprof
@section Profiling an Ada Program using gprof
@cindex gprof
@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
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
@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
* 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
@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
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
