@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
@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
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
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
@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{-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:
@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:
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.
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}.
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
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
@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
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
@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.
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
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
@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
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
@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
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
projects / gcc.git / commitdiff