-f\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@c %**start of header
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
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
+under the terms of the GNU Free Documentation License, Version 1.3 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
@macro ovar{varname}
@r{[}@var{\varname\}@r{]}@c
@end macro
+@c Status as of November 2009:
+@c Unfortunately texi2pdf and texi2html treat the trailing "@c"
+@c differently, and faulty output is produced by one or the other
+@c depending on whether the "@c" is present or absent.
+@c As a result, the @ovar macro is not used, and all invocations
+@c of the @ovar macro have been expanded inline.
+
@settitle @value{EDITION} User's Guide @value{PLATFORM}
@dircategory GNU Ada tools
The Cross-Referencing Tools gnatxref and gnatfind
-* gnatxref Switches::
-* gnatfind Switches::
+* Switches for gnatxref::
+* Switches for gnatfind::
* Project Files for gnatxref and gnatfind::
* Regular Expressions in gnatfind and gnatxref::
* Examples of gnatxref Usage::
* gnatcheck Rule Options::
* Adding the Results of Compiler Checks to gnatcheck Output::
* Project-Wide Checks::
+* Rule exemption::
* Predefined Rules::
+* Example of gnatcheck Usage::
Sample Bodies Using gnatstub
* Linux-Specific Considerations::
* AIX-Specific Considerations::
* Irix-Specific Considerations::
+* RTX-Specific Considerations::
+* HP-UX-Specific Considerations::
Example of Binder Output File
The basic command for compiling a file containing an Ada unit is
@smallexample
-$ gcc -c @ovar{switches} @file{file name}
+@c $ gcc -c @ovar{switches} @file{file name}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gcc -c @r{[}@var{switches}@r{]} @file{file name}
@end smallexample
@noindent
Library (RTL) ALI files.
@ifclear vms
-@item -O@ovar{n}
+@c @item -O@ovar{n}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+@item -O@r{[}@var{n}@r{]}
@cindex @option{-O} (@command{gcc})
@var{n} controls the optimization level.
@item
The switches
-@option{^-gnatz^/DISTRIBUTION_STUBS^}, @option{-gnatzc}, and @option{-gnatzr}
-may not be combined with any other switches.
+^^@option{/DISTRIBUTION_STUBS=},^
+@option{-gnatzc} and @option{-gnatzr} may not be combined with any other
+switches, and only one of them may appear in the command line.
@ifclear vms
@item
Once a ``V'' appears in the string (that is a use of the @option{-gnatV}
switch), then all further characters in the switch are interpreted
as validity checking options (@pxref{Validity Checking}).
+
+@item
+Option ``em'', ``ec'', ``ep'', ``l='' and ``R'' must be the last options in
+a combined list of options.
@end ifclear
@end itemize
This switch disables warnings for a @code{with} of an internal GNAT
implementation unit.
+@item -gnatw.i
+@emph{Activate warnings on overlapping actuals.}
+@cindex @option{-gnatw.i} (@command{gcc})
+This switch enables a warning on statically detectable overlapping actuals in
+a subprogram call, when one of the actuals is an in-out parameter, and the
+types of the actuals are not by-copy types. The warning is off by default,
+and is not included under -gnatwa.
+
+@item -gnatw.I
+@emph{Disable warnings on overlapping actuals.}
+@cindex @option{-gnatw.I} (@command{gcc})
+This switch disables warnings on overlapping actuals in a call..
+
@item -gnatwj
@emph{Activate warnings on obsolescent features (Annex J).}
@cindex @option{-gnatwj} (@command{gcc})
If the token preceding a left parenthesis ends with a letter or digit, then
a space must separate the two tokens.
+@item
+if the token following a right parenthesis starts with a letter or digit, then
+a space must separate the two tokens.
+
@item
A right parenthesis must either be the first non-blank character on
a line, or it must be preceded by a non-blank character.
XTRA_PARENS, and DOS_LINE_ENDINGS. In addition
@end ifset
-
-
The switch
@ifclear vms
@option{-gnatyN}
Used to list an equivalent declaration for an internally generated
type that is referenced elsewhere in the listing.
-@item freeze @var{type-name} @ovar{actions}
+@c @item freeze @var{type-name} @ovar{actions}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+@item freeze @var{type-name} @r{[}@var{actions}@r{]}
Shows the point at which @var{type-name} is frozen, with possible
associated actions to be performed at the freeze point.
@table @option
-@item -gnatem^^=^@var{path}
+@item -gnatem=@var{path}
@cindex @option{-gnatem} (@command{gcc})
A mapping file is a way to communicate to the compiler two mappings:
from unit names to file names (without any directory information) and from
sources are read over a slow network connection. In normal operation,
you need not be concerned with the format or use of mapping files,
and the @option{-gnatem} switch is not a switch that you would use
-explicitly. it is intended only for use by automatic tools such as
+explicitly. It is intended primarily for use by automatic tools such as
@command{gnatmake} running under the project file facility. The
description here of the format of mapping files is provided
for completeness and for possible use by other tools.
-A mapping file is a sequence of sets of three lines. In each set,
-the first line is the unit name, in lower case, with ``@code{%s}''
-appended for
-specs and ``@code{%b}'' appended for bodies; the second line is the
+A mapping file is a sequence of sets of three lines. In each set, the
+first line is the unit name, in lower case, with @code{%s} appended
+for specs and @code{%b} appended for bodies; the second line is the
file name; and the third line is the path name.
Example:
/gnat/project1/sources/main.2.ada
@end smallexample
-When the switch @option{-gnatem} is specified, the compiler will create
-in memory the two mappings from the specified file. If there is any problem
-(nonexistent file, truncated file or duplicate entries), no mapping will
-be created.
+When the switch @option{-gnatem} is specified, the compiler will
+create in memory the two mappings from the specified file. If there is
+any problem (nonexistent file, truncated file or duplicate entries),
+no mapping will be created.
-Several @option{-gnatem} switches may be specified; however, only the last
-one on the command line will be taken into account.
+Several @option{-gnatem} switches may be specified; however, only the
+last one on the command line will be taken into account.
-When using a project file, @command{gnatmake} create a temporary mapping file
-and communicates it to the compiler using this switch.
+When using a project file, @command{gnatmake} creates a temporary
+mapping file and communicates it to the compiler using this switch.
@end table
The form of the @code{gnatbind} command is
@smallexample
-$ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches}
+@c $ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatbind @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]} @r{[}@var{switches}@r{]}
@end smallexample
@noindent
The form of the @command{gnatlink} command is
@smallexample
-$ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]}
- @ovar{non-Ada objects} @ovar{linker options}
+@c $ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]}
+@c @ovar{non-Ada objects} @ovar{linker options}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatlink @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]}
+ @r{[}@var{non-Ada objects}@r{]} @r{[}@var{linker options}@r{]}
+
@end smallexample
@noindent
The usual form of the @command{gnatmake} command is
@smallexample
-$ gnatmake @ovar{switches} @var{file_name}
- @ovar{file_names} @ovar{mode_switches}
+@c $ gnatmake @ovar{switches} @var{file_name}
+@c @ovar{file_names} @ovar{mode_switches}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatmake @r{[}@var{switches}@r{]} @var{file_name}
+ @r{[}@var{file_names}@r{]} @r{[}@var{mode_switches}@r{]}
@end smallexample
@noindent
@item ^-C^/MAPPING^
@cindex @option{^-C^/MAPPING^} (@command{gnatmake})
-Use a temporary mapping file. A mapping file is a way to communicate to the
-compiler two mappings: from unit names to file names (without any directory
-information) and from file names to path names (with full directory
-information). These mappings are used by the compiler to short-circuit the path
-search. When @command{gnatmake} is invoked with this switch, it will create
-a temporary mapping file, initially populated by the project manager,
-if @option{^-P^/PROJECT_FILE^} is used, otherwise initially empty.
-Each invocation of the compiler will add the newly accessed sources to the
-mapping file. This will improve the source search during the next invocation
-of the compiler.
+Use a temporary mapping file. A mapping file is a way to communicate
+to the compiler two mappings: from unit names to file names (without
+any directory information) and from file names to path names (with
+full directory information). A mapping file can make the compiler's
+file searches faster, especially if there are many source directories,
+or the sources are read over a slow network connection. If
+@option{^-P^/PROJECT_FILE^} is used, a mapping file is always used, so
+@option{^-C^/MAPPING^} is unnecessary; in this case the mapping file
+is initially populated based on the project file. If
+@option{^-C^/MAPPING^} is used without
+@option{^-P^/PROJECT_FILE^},
+the mapping file is initially empty. Each invocation of the compiler
+will add any newly accessed sources to the mapping file.
@item ^-C=^/USE_MAPPING_FILE=^@var{file}
@cindex @option{^-C=^/USE_MAPPING^} (@command{gnatmake})
@ifclear vms
@item -eL
@cindex @option{-eL} (@command{gnatmake})
+@cindex symbolic links
Follow all symbolic links when processing project files.
+This should be used if your project uses symbolic links for files or
+directories, but is not needed in other cases.
+
+@cindex naming scheme
+This also assumes that no directory matches the naming scheme for files (for
+instance that you do not have a directory called "sources.ads" when using the
+default GNAT naming scheme).
+
+When you do not have to use this switch (ie by default), gnatmake is able to
+save a lot of system calls (several per source file and object file), which
+can result in a significant speed up to load and manipulate a project file,
+especially when using source files from a remote system.
+
@end ifclear
@item ^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^
@code{gnatelim} has the following command-line interface:
@smallexample
-$ gnatelim @ovar{options} name
+$ gnatelim [@var{options}] name
@end smallexample
@noindent
The @code{gnatchop} command has the form:
@smallexample
+@c $ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]}
+@c @ovar{directory}
+@c Expanding @ovar macro inline (explanation in macro def comments)
$ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]}
- @ovar{directory}
+ @r{[}@var{directory}@r{]}
@end smallexample
@noindent
The usual form of the @code{gnatname} command is
@smallexample
-$ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}
- @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]}
+@c $ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}
+@c @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatname @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]}
+ @r{[}--and @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]}@r{]}
@end smallexample
@noindent
@item
@code{Cross_Reference}
@item
+@code{Check}
+@item
@code{Eliminate}
@item
@code{Pretty_Printer}
@item
package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
+@item
+package @code{Check} for command CHECK
+(invoking @code{^gnatcheck^gnatcheck^})
+
@item
package @code{Metrics} for command METRIC
(invoking @code{^gnatmetric^gnatmetric^})
use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}).
@menu
-* gnatxref Switches::
-* gnatfind Switches::
+* Switches for gnatxref::
+* Switches for gnatfind::
* Project Files for gnatxref and gnatfind::
* Regular Expressions in gnatfind and gnatxref::
* Examples of gnatxref Usage::
* Examples of gnatfind Usage::
@end menu
-@node gnatxref Switches
+@node Switches for gnatxref
@section @code{gnatxref} Switches
@noindent
The command invocation for @code{gnatxref} is:
@smallexample
-$ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
+@c $ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatxref @r{[}@var{switches}@r{]} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
@end smallexample
@noindent
you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of
@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}.
-@node gnatfind Switches
+@node Switches for gnatfind
@section @code{gnatfind} Switches
@noindent
The command line for @code{gnatfind} is:
@smallexample
-$ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
- @r{[}@var{file1} @var{file2} @dots{}]
+@c $ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
+@c @r{[}@var{file1} @var{file2} @dots{}]
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatfind @r{[}@var{switches}@r{]} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
+ @r{[}@var{file1} @var{file2} @dots{}@r{]}
@end smallexample
@noindent
The @command{gnatpp} command has the form
@smallexample
-$ gnatpp @ovar{switches} @var{filename}
+@c $ gnatpp @ovar{switches} @var{filename}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatpp @r{[}@var{switches}@r{]} @var{filename}
@end smallexample
@noindent
@item ^-files @var{filename}^/FILES=@var{output_file}^
@cindex @option{^-files^/FILES^} (@code{gnatpp})
Take the argument source files from the specified file. This file should be an
-ordinary textual file containing file names separated by spaces or
-line breaks. You can use this switch more then once in the same call to
-@command{gnatpp}. You also can combine this switch with explicit list of
+ordinary text file containing file names separated by spaces or
+line breaks. You can use this switch more than once in the same call to
+@command{gnatpp}. You also can combine this switch with an explicit list of
files.
@item ^-v^/VERBOSE^
The @command{gnatmetric} command has the form
@smallexample
-$ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
+@c $ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatmetric @r{[}@var{switches}@r{]} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
@end smallexample
@noindent
@cindex @option{^-d^/DIRECTORY^} (@command{gnatmetric})
@item ^-d @var{output_dir}^/DIRECTORY=@var{output_dir}^
-Put textual files with detailed metrics into @var{output_dir}
+Put text files with detailed metrics into @var{output_dir}
@cindex @option{^-o^/SUFFIX_DETAILS^} (@command{gnatmetric})
@item ^-o @var{file_suffix}^/SUFFIX_DETAILS=@var{file_suffix}^
@cindex @option{^-files^/FILES^} (@code{gnatmetric})
Take the argument source files from the specified file. This file should be an
ordinary text file containing file names separated by spaces or
-line breaks. You can use this switch more then once in the same call to
+line breaks. You can use this switch more than once in the same call to
@command{gnatmetric}. You also can combine this switch with
an explicit list of files.
@ifclear vms
@smallexample
-$ gnatkr @var{name} @ovar{length}
+@c $ gnatkr @var{name} @ovar{length}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatkr @var{name} @r{[}@var{length}@r{]}
@end smallexample
@end ifclear
To call @code{gnatprep} use
@smallexample
-$ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile}
+@c $ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatprep @r{[}@var{switches}@r{]} @var{infile} @var{outfile} @r{[}@var{deffile}@r{]}
@end smallexample
@noindent
Here is an example of simple library interface for use with C main program:
@smallexample @c ada
-package Interface is
+package My_Package is
procedure Do_Something;
pragma Export (C, Do_Something, "do_something");
procedure Do_Something_Else;
pragma Export (C, Do_Something_Else, "do_something_else");
-end Interface;
+end My_Package;
@end smallexample
@noindent
The @code{gnatmem} command has the form
@smallexample
- $ gnatmem @ovar{switches} user_program
+@c $ gnatmem @ovar{switches} user_program
+@c Expanding @ovar macro inline (explanation in macro def comments)
+ $ gnatmem @r{[}@var{switches}@r{]} @var{user_program}
@end smallexample
@noindent
Invoking @command{gnatcheck} on the command line has the form:
@smallexample
-$ gnatcheck @ovar{switches} @{@var{filename}@}
+@c $ gnatcheck @ovar{switches} @{@var{filename}@}
+@c @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
+@c @r{[}-cargs @var{gcc_switches}@r{]} -rules @var{rule_options}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatcheck @r{[}@var{switches}@r{]} @{@var{filename}@}
@r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
- @r{[}-cargs @var{gcc_switches}@r{]} @r{[}-rules @var{rule_options}@r{]}
+ @r{[}-cargs @var{gcc_switches}@r{]} -rules @var{rule_options}
@end smallexample
@noindent
@end itemize
@noindent
-Either a @file{@var{filename}} or an @file{@var{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::
* gnatcheck Rule Options::
* Adding the Results of Compiler Checks to gnatcheck Output::
* Project-Wide Checks::
+* Rule exemption::
* Predefined Rules::
+* Example of gnatcheck Usage::
@end menu
@node Format of the Report File
The @command{gnatcheck} tool outputs on @file{stdout} all messages concerning
rule violations.
It also creates a text file that
-contains the complete report of the last gnatcheck run. By default this file is
-named named @file{^gnatcheck.out^GNATCHECK.OUT^} and it is located in the current
-directory, @option{^-o^/OUTPUT^} option can be used to change the name and/or
-location of the report file. This report contains:
+contains the complete report of the last gnatcheck run. By default this file
+is named named @file{^gnatcheck.out^GNATCHECK.OUT^} and it is located in the
+current directory; the @option{^-o^/OUTPUT^} option can be used to change the
+name and/or location of the report file. This report contains:
@itemize @bullet
-@item a list of the Ada source files being checked,
-@item a list of enabled and disabled rules,
-@item a list of the diagnostic messages, ordered in three different ways
-and collected in three separate
-sections. Section 1 contains the raw list of diagnostic messages. It
-corresponds to the output going to @file{stdout}. Section 2 contains
-messages ordered by rules.
-Section 3 contains messages ordered by source files.
+@item date and time of @command{gnatcheck} run, the version of
+the tool that has generated this report and the full parameters
+of the @command{gnatcheck} invocation;
+@item list of enabled rules;
+@item total number of detected violations;
+@item list of source files where rule violations have been detected;
+@item list of source files where no violations have been detected.
@end itemize
@node General gnatcheck Switches
@cindex @option{^-a^/ALL^} (@command{gnatcheck})
@item ^-a^/ALL^
Process all units including those with read-only ALI files such as
-those from GNAT Run-Time library.
+those from the GNAT Run-Time library.
@ifclear vms
@ignore
@cindex @option{-dd} (@command{gnatcheck})
@item -dd
-Progress indicator mode (for use in GPS)
+Progress indicator mode (for use in GPS).
@end ifclear
@cindex @option{^-h^/HELP^} (@command{gnatcheck})
@cindex @option{^-log^/LOG^} (@command{gnatcheck})
@item ^-log^/LOG^
-Duplicate all the output sent to Stderr into a log file. The log file is
-named @var{gnatcheck.log} and is located in the current directory.
+Duplicate all the output sent to @file{stderr} into a log file. The log file
+is named @file{gnatcheck.log} and is located in the current directory.
@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,
+@item ^-m@i{nnnn}^/DIAGNOSTIC_LIMIT=@i{nnnn}^
+Maximum number of diagnostics to be sent to @file{stdout}, where @i{nnnn} is in
+the range 0@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.
+the number of diagnostic messages to be output.
@cindex @option{^-q^/QUIET^} (@command{gnatcheck})
@item ^-q^/QUIET^
-Quiet mode. All the diagnoses about rule violations are placed in the
-@command{gnatcheck} report file only, without duplicating in @file{stdout}.
+Quiet mode. All the diagnostics about rule violations are placed in the
+@command{gnatcheck} report file only, without duplication on @file{stdout}.
@cindex @option{^-s^/SHORT^} (@command{gnatcheck})
@item ^-s^/SHORT^
Short format of the report file (no version information, no list of applied
rules, no list of checked sources is included)
-@cindex @option{^-s1^/COMPILER_STYLE^} (@command{gnatcheck})
-@item ^-s1^/COMPILER_STYLE^
-Include the compiler-style section in the report file
-
-@cindex @option{^-s2^/BY_RULES^} (@command{gnatcheck})
-@item ^-s2^/BY_RULES^
-Include the section containing diagnoses ordered by rules in the report file
-
-@cindex @option{^-s3^/BY_FILES_BY_RULES^} (@command{gnatcheck})
-@item ^-s3^/BY_FILES_BY_RULES^
-Include the section containing diagnoses ordered by files and then by rules
-in the report file
+@cindex @option{^--include-file=@var{file}^/INCLUDE_FILE=@var{file}^} (@command{gnatcheck})
+@item ^--include-file^/INCLUDE_FILE^
+Append the content of the specified text file to the report file
@cindex @option{^-t^/TIME^} (@command{gnatcheck})
@item ^-t^/TIME^
@cindex @option{-from} (@command{gnatcheck})
@item -from=@var{rule_option_filename}
-Read the rule options from the text file @var{rule_option_filename}, referred as
-``rule file'' below.
+Read the rule options from the text file @var{rule_option_filename}, referred
+to as a ``coding standard file'' below.
@end table
@noindent
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})
+A coding standard file is a text file that contains a set of rule options
+described above.
+@cindex Coding standard file (for @code{gnatcheck})
The file may contain empty lines and Ada-style comments (comment
-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.
+lines and end-of-line comments). There can be several rule options on a
+single line (separated by a space).
-A rule file may contain other @option{-from=@var{rule_option_filename}}
+A coding standard file may reference other coding standard files by including
+more @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
+corresponding coding standard file during processing. In case a
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.
+processing fails with an error message.
@node Adding the Results of Compiler Checks to gnatcheck Output
@table @option
@item Restrictions
-To record restrictions violations (that are performed by the compiler if the
+To record restrictions violations (which are performed by the compiler if the
pragma @code{Restrictions} or @code{Restriction_Warnings} are given),
-use the rule named
-@code{Restrictions} with the same parameters as pragma
+use the @code{Restrictions} rule
+with the same parameters as pragma
@code{Restrictions} or @code{Restriction_Warnings}.
@item Style_Checks
-To record compiler style checks(@pxref{Style Checking}), use the rule named
-@code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
-which enables all the standard style checks that corresponds to @option{-gnatyy}
-GNAT style check option, or a string that has exactly the same
-structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
-@code{Style_Checks} (for further information about this pragma,
-@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}). For example,
-@code{+RStyle_Checks:O} rule option activates and adds to @command{gnatcheck}
-output the compiler style check that corresponds to
+To record compiler style checks (@pxref{Style Checking}), use the
+@code{Style_Checks} rule.
+This rule takes a parameter in one of the following forms:
+@itemize
+@item
+@code{All_Checks},
+which enables the standard style checks corresponding to the @option{-gnatyy}
+GNAT style check option, or
+
+@item
+a string with the same
+structure and semantics as the @code{string_LITERAL} parameter of the
+GNAT pragma @code{Style_Checks}
+(for further information about this pragma,
+@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
+@end itemize
+
+@noindent
+For example, the
+@code{+RStyle_Checks:O} rule option activates
+the compiler style check that corresponds to
@code{-gnatyO} style check option.
@item Warnings
-To record compiler warnings (@pxref{Warning Message Control}), use the rule
-named @code{Warnings} with a parameter that is a valid
-@i{static_string_expression} argument of GNAT pragma @code{Warnings}
-(for further information about this pragma, @pxref{Pragma Warnings,,,
-gnat_rm, GNAT Reference Manual}). Note, that in case of gnatcheck
+To record compiler warnings (@pxref{Warning Message Control}), use the
+@code{Warnings} rule with a parameter that is a valid
+@i{static_string_expression} argument of the GNAT pragma @code{Warnings}
+(for further information about this pragma,
+@pxref{Pragma Warnings,,,gnat_rm, GNAT Reference Manual}).
+Note that in case of gnatcheck
's' parameter, that corresponds to the GNAT @option{-gnatws} option, disables
all the specific warnings, but not suppresses the warning mode,
and 'e' parameter, corresponding to @option{-gnatwe} that means
@end smallexample
+@node Rule exemption
+@section Rule exemption
+@cindex Rule exemption (for @command{gnatcheck})
+
+@noindent
+One of the most useful applications of @command{gnatcheck} is to
+automate the enforcement of project-specific coding standards,
+for example in safety-critical systems where particular features
+must be restricted in order to simplify the certification effort.
+However, it may sometimes be appropriate to violate a coding standard rule,
+and in such cases the rationale for the violation should be provided
+in the source program itself so that the individuals
+reviewing or maintaining the program can immediately understand the intent.
+
+The @command{gnatcheck} tool supports this practice with the notion of
+a ``rule exemption'' covering a specific source code section. Normally
+rule violation messages are issued both on @file{stderr}
+and in a report file. In contrast, exempted violations are not listed on
+@file{stderr}; thus users invoking @command{gnatcheck} interactively
+(e.g. in its GPS interface) do not need to pay attention to known and
+justified violations. However, exempted violations along with their
+justification are documented in a special section of the report file that
+@command{gnatcheck} generates.
+
+@menu
+* Using pragma Annotate to Control Rule Exemption::
+* gnatcheck Annotations Rules::
+@end menu
+
+@node Using pragma Annotate to Control Rule Exemption
+@subsection Using pragma @code{Annotate} to Control Rule Exemption
+@cindex Using pragma Annotate to control rule exemption
+
+@noindent
+Rule exemption is controlled by pragma @code{Annotate} when its first
+argument is ``gnatcheck''. The syntax of @command{gnatcheck}'s
+exemption control annotations is as follows:
+
+@smallexample @c ada
+@group
+pragma Annotate (gnatcheck, @i{exemption_control}, @i{Rule_Name}, [@i{justification}]);
+
+@i{exemption_control} ::= Exempt_On | Exempt_Off
+
+@i{Rule_Name} ::= string_literal
+
+@i{justification} ::= string_literal
+@end group
+@end smallexample
+
+@noindent
+When a @command{gnatcheck} annotation has more then four arguments,
+@command{gnatcheck} issues a warning and ignores the additional arguments.
+If the additional arguments do not follow the syntax above,
+@command{gnatcheck} emits a warning and ignores the annotation.
+
+The @i{@code{Rule_Name}} argument should be the name of some existing
+@command{gnatcheck} rule.
+Otherwise a warning message is generated and the pragma is
+ignored. If @code{Rule_Name} denotes a rule that is not activated by the given
+@command{gnatcheck} call, the pragma is ignored and no warning is issued.
+
+A source code section where an exemption is active for a given rule is
+delimited by an @code{exempt_on} and @code{exempt_off} annotation pair:
+
+@smallexample @c ada
+pragma Annotate (gnatcheck, Exempt_On, Rule_Name, "justification");
+-- source code section
+pragma Annotate (gnatcheck, Exempt_Off, Rule_Name);
+@end smallexample
+
+
+@node gnatcheck Annotations Rules
+@subsection @command{gnatcheck} Annotations Rules
+@cindex @command{gnatcheck} annotations rules
+
+@itemize @bullet
+
+@item
+An ``Exempt_Off'' annotation can only appear after a corresponding
+``Exempt_On'' annotation.
+
+@item
+Exempted source code sections are only based on the source location of the
+annotations. Any source construct between the two
+annotations is part of the exempted source code section.
+
+@item
+Exempted source code sections for different rules are independent. They can
+be nested or intersect with one another without limitation.
+Creating nested or intersecting source code sections for the same rule is
+not allowed.
+
+@item
+Malformed exempted source code sections are reported by a warning, and
+the corresponding rule exemptions are ignored.
+
+@item
+When an exempted source code section does not contain at least one violation
+of the exempted rule, a warning is emitted on @file{stderr}.
+
+@item
+If an ``Exempt_On'' annotation pragma does not have a matching
+``Exempt_Off'' annotation pragma in the same compilation unit, then the
+exemption for the given rule is ignored and a warning is issued.
+@end itemize
+
+
@node Predefined Rules
@section Predefined Rules
@cindex Predefined rules (for @command{gnatcheck})
@cindex @code{Anonymous_Subtypes} rule (for @command{gnatcheck})
@noindent
-Flag all uses of anonymous subtypes. A use of an anonymous subtype is
+Flag all uses of anonymous subtypes (except cases when subtype indication
+is a part of a record component definition, and this subtype indication
+depends on a discriminant). A use of an anonymous subtype is
any instance of a subtype indication with a constraint, other than one
that occurs immediately within a subtype declaration. Any use of a range
other than as a constraint used immediately within a subtype declaration
@itemize @bullet
@item
it contains at least one complex declaration such as a subprogram body,
-package, task, protected object declaration, or a generic instantiation
+package, task, protected declaration, or a generic instantiation
(except instantiation of @code{Ada.Unchecked_Conversion});
@item
depths of the immediate parent and immediate progenitors.
This rule does not flag private extension
-declarations. In the case of a private extension, the correspondong full
+declarations. In the case of a private extension, the corresponding full
declaration is checked.
This rule has the following (mandatory) parameter for the @option{+R} option:
@table @emph
@item N
-Integer not less then -1 specifying the maximal allowed depth of any inheritance
+Integer not less than -1 specifying the maximal allowed depth of any inheritance
hierarchy. If the rule parameter is set to -1, the rule flags all the declarations
of tagged and interface types.
@end table
@cindex @code{Deeply_Nested_Inlining} rule (for @command{gnatcheck})
@noindent
-Flags the body of a subprogram (or generic subprogram) if
-pragma Inline has been applied to the subprogram but the body
-contains a call to another inlined subprogram that results in nested inlining
+Flags a subprogram (or generic subprogram) if
+pragma Inline has been applied to the subprogram but the subprogram
+calls to another inlined subprogram that results in nested inlining
with nesting depth exceeding the value specified by the
@option{N} rule parameter.
-This rule assumes that pragma Inline applies equally to calls on
-subprograms regardless of whether the subprogram declaration appears in the
-same compilation unit as the call, or in a separately compiled
-(e.g., @i{with}ed) unit.
-
-This rule may be useful when either the @option{-gnatn} or @option{-gnatN}
-option is used.
-
-If a subprogram should be flagged according to this rule, the body declaration
-is flagged only if it is not a completion of a subprogram declaration.
-
This rule requires the global analysis of all the compilation units that
are @command{gnatcheck} arguments; such analysis may affect the tool's
performance.
@cindex @code{Positional_Generic_Parameters} rule (for @command{gnatcheck})
@noindent
-Flag each instantiation using positional parameter notation.
+Flag each positional actual generic parameter except for the case when
+the generic unit being iinstantiated has exactly one generic formal
+parameter.
This rule has no parameters.
@cindex @code{Positional_Parameters} rule (for @command{gnatcheck})
@noindent
-Flag each subprogram or entry call using positional parameter notation,
+Flag each positional parameter notation in a subprogram or entry call,
except for the following:
@itemize @bullet
@item
-Invocations of prefix or infix operators are not flagged
+Parameters of calls to of prefix or infix operators are not flagged
@item
If the called subprogram or entry has only one formal parameter,
-the call is not flagged;
+the parameter of the call is not flagged;
@item
If a subprogram call uses the @emph{Object.Operation} notation, then
@itemize @minus
Flag each function returning an unconstrained array. Function declarations,
function bodies (and body stubs) having no separate specifications,
and generic function instantiations are checked.
-Generic function declarations, function calls and function renamings are
+Function calls and function renamings are
not checked.
+Generic function declarations, and function declarations in generic
+packages are not checked, instead this rule checks the results of
+generic instantiations (that is, expanded specification and expanded
+body corresponding to an instantiation).
+
This rule has no parameters.
@node Universal_Ranges
This rule has no parameters.
+@node Example of gnatcheck Usage
+@section Example of @command{gnatcheck} Usage
+
+@noindent
+Here is a simple example. Suppose that in the current directory we have a
+project file named @file{gnatcheck_example.gpr} with the following content:
+
+@smallexample @c projectfile
+project Gnatcheck_Example is
+
+ for Source_Dirs use ("src");
+ for Object_Dir use "obj";
+ for Main use ("main.adb");
+
+ package Check is
+ for Default_Switches ("ada") use ("-rules", "-from=coding_standard");
+ end Check;
+
+end Gnatcheck_Example;
+@end smallexample
+
+@noindent
+And the file named @file{coding_standard} is also located in the current
+directory and has the following content:
+
+@smallexample
+-----------------------------------------------------
+-- This is a sample gnatcheck coding standard file --
+-----------------------------------------------------
+
+-- First, turning on rules, that are directly implemented in gnatcheck
++RAbstract_Type_Declarations
++RAnonymous_Arrays
++RLocal_Packages
++RFloat_Equality_Checks
++REXIT_Statements_With_No_Loop_Name
+
+-- Then, activating compiler checks of interest:
++RStyle_Checks:e
+-- This style check checks if a unit name is present on END keyword that
+-- is the end of the unit declaration
+@end smallexample
+
+@noindent
+And the subdirectory @file{src} contains the following Ada sources:
+
+@file{pack.ads}:
+
+@smallexample @c ada
+package Pack is
+ type T is abstract tagged private;
+ procedure P (X : T) is abstract;
+
+ package Inner is
+ type My_Float is digits 8;
+ function Is_Equal (L, R : My_Float) return Boolean;
+ end Inner;
+private
+ type T is abstract tagged null record;
+end;
+@end smallexample
+
+@noindent
+@file{pack.adb}:
+
+@smallexample @c ada
+package body Pack is
+ package body Inner is
+ function Is_Equal (L, R : My_Float) return Boolean is
+ begin
+ return L = R;
+ end;
+ end Inner;
+end Pack;
+@end smallexample
+
+@noindent
+and @file{main.adb}
+
+@smallexample @c ada
+with Pack; use Pack;
+procedure Main is
+
+ pragma Annotate
+ (gnatcheck, Exempt_On, "Anonymous_Arrays", "this one is fine");
+ Float_Array : array (1 .. 10) of Inner.My_Float;
+ pragma Annotate (gnatcheck, Exempt_Off, "Anonymous_Arrays");
+
+ Another_Float_Array : array (1 .. 10) of Inner.My_Float;
+
+ use Inner;
+
+ B : Boolean := False;
+
+begin
+ for J in Float_Array'Range loop
+ if Is_Equal (Float_Array (J), Another_Float_Array (J)) then
+ B := True;
+ exit;
+ end if;
+ end loop;
+end Main;
+@end smallexample
+
+@noindent
+And suppose we call @command{gnatcheck} from the current directory using
+the @command{gnat} driver:
+
+@smallexample
+ gnat check -Pgnatcheck_example.gpr
+@end smallexample
+
+@noindent
+As a result, @command{gnatcheck} is called to check all the files from the
+project @file{gnatcheck_example.gpr} using the coding standard defined by
+the file @file{coding_standard}. As the result, the @command{gnatcheck}
+report file named @file{gnatcheck.out} will be created in the current
+directory, and it will have the following content:
+
+@smallexample
+RULE CHECKING REPORT
+
+1. OVERVIEW
+
+Date and time of execution: 2009.10.28 14:17
+Tool version: GNATCHECK (built with ASIS 2.0.R for GNAT Pro 6.3.0w (20091016))
+Command line:
+
+gnatcheck -files=.../GNAT-TEMP-000004.TMP -cargs -gnatec=.../GNAT-TEMP-000003.TMP -rules -from=coding_standard
+
+Coding standard (applied rules):
+ Abstract_Type_Declarations
+ Anonymous_Arrays
+ EXIT_Statements_With_No_Loop_Name
+ Float_Equality_Checks
+ Local_Packages
+
+ Compiler style checks: -gnatye
+
+Number of coding standard violations: 6
+Number of exempted coding standard violations: 1
+
+2. DETECTED RULE VIOLATIONS
+
+2.1. NON-EXEMPTED VIOLATIONS
+
+Source files with non-exempted violations
+ pack.ads
+ pack.adb
+ main.adb
+
+List of violations grouped by files, and ordered by increasing source location:
+
+pack.ads:2:4: declaration of abstract type
+pack.ads:5:4: declaration of local package
+pack.ads:10:30: declaration of abstract type
+pack.ads:11:1: (style) "end Pack" required
+pack.adb:5:19: use of equality operation for float values
+pack.adb:6:7: (style) "end Is_Equal" required
+main.adb:9:26: anonymous array type
+main.adb:19:10: exit statement with no loop name
+
+2.2. EXEMPTED VIOLATIONS
+
+Source files with exempted violations
+ main.adb
+
+List of violations grouped by files, and ordered by increasing source location:
+
+main.adb:6:18: anonymous array type
+ (this one is fine)
+
+2.3. SOURCE FILES WITH NO VIOLATION
+
+ No files without violations
+
+END OF REPORT
+@end smallexample
+
@c *********************************
@node Creating Sample Bodies Using gnatstub
@command{gnatstub} has the command-line interface of the form
@smallexample
-$ gnatstub @ovar{switches} @var{filename} @ovar{directory}
+@c $ gnatstub @ovar{switches} @var{filename} @ovar{directory}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatstub @r{[}@var{switches}@r{]} @var{filename} @r{[}@var{directory}@r{]}
@end smallexample
@noindent
@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.
+GNAT now comes with a 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 capability is not intended to generate 100% correct Ada specs,
+and will is some cases require manual adjustments, although it can often
+be used out of the box in practice.
+
+Some of the known limitations include:
+
+@itemize @bullet
+@item only very simple character constant macros are translated into Ada
+constants. Function macros (macros with arguments) are partially translated
+as comments, to be completed manually if needed.
+@item some extensions (e.g. vector types) are not supported
+@item pointers to pointers or complex structures are mapped to System.Address
+@end itemize
The code generated is using the Ada 2005 syntax, which makes it
easier to interface with other languages than previous versions of Ada.
The command line is as follow:
@smallexample
-$ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files}
+@c $ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ perl gnathtml.pl @r{[}@var{^switches^options^}@r{]} @var{ada-files}
@end smallexample
@noindent
Alternatively, you may run the script using the following command line:
@smallexample
-$ perl gnathtml.pl @ovar{switches} @var{files}
+@c $ perl gnathtml.pl @ovar{switches} @var{files}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ perl gnathtml.pl @r{[}@var{switches}@r{]} @var{files}
@end smallexample
@ifset vms
For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
attributes are recognized, although only a subset of them can sensibly
be implemented. The description of pragmas in
-@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
indicates whether or not they are applicable to non-VMS systems.
@menu
@noindent
The pragma @code{Extend_System} is a configuration pragma that
is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma
-Extend_System,,, gnat_rm, GNAT Reference Manual} for further details.
+Extend_System,,, gnat_rm, GNAT Reference Manual}, for further details.
HP Ada does not allow the recompilation of the package
@code{SYSTEM}. Instead HP Ada provides several pragmas
@code{TO_ADDRESS}
function for type @code{UNSIGNED_LONGWORD} is changed to
@code{TO_ADDRESS_LONG}.
-@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual} for a
+@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual}, for a
discussion of why this change was necessary.
@noindent
* AIX-Specific Considerations::
* Irix-Specific Considerations::
* RTX-Specific Considerations::
+* HP-UX-Specific Considerations::
@end menu
@node Summary of Run-Time Configurations
@end itemize
+@node HP-UX-Specific Considerations
+@section HP-UX-Specific Considerations
+@cindex HP-UX Scheduling
+
+@noindent
+On HP-UX, appropriate privileges are required to change the scheduling
+parameters of a task. The calling process must have appropriate
+privileges or be a member of a group having @code{PRIV_RTSCHED} access to
+successfully change the scheduling parameters.
+
+By default, GNAT uses the @code{SCHED_HPUX} policy. To have access to the
+priority range 0-31 either the @code{FIFO_Within_Priorities} or the
+@code{Round_Robin_Within_Priorities} scheduling policies need to be set.
+
+To specify the @code{FIFO_Within_Priorities} scheduling policy you can use
+one of the following:
+
+@itemize @bullet
+@item
+@code{pragma Time_Slice (0.0)}
+@cindex pragma Time_Slice
+@item
+the corresponding binder option @option{-T0}
+@cindex @option{-T0} option
+@item
+@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
+@cindex pragma Task_Dispatching_Policy
+@end itemize
+
+@noindent
+To specify the @code{Round_Robin_Within_Priorities}, scheduling policy
+you should use @code{pragma Time_Slice} with a
+value greater than @code{0.0}, or use the corresponding @option{-T}
+binder option, or set the @code{pragma Task_Dispatching_Policy
+(Round_Robin_Within_Priorities)}.
+
@c *******************************
@node Example of Binder Output File
@appendix Example of Binder Output File
@smallexample
@cartouche
-$ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
+@c $ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatdll @r{[}@var{switches}@r{]} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
@end cartouche
@end smallexample
You may specify any of the following switches to @code{gnatdll}:
@table @code
-@item -a@ovar{address}
+@c @item -a@ovar{address}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+@item -a@r{[}@var{address}@r{]}
@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,
is
@smallexample
-$ dlltool @ovar{switches}
+@c $ dlltool @ovar{switches}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ dlltool @r{[}@var{switches}@r{]}
@end smallexample
@noindent
projects / thirdparty / gcc.git / blobdiff