-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::
* 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
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
* Project-Wide Checks::
* Rule exemption::
* Predefined Rules::
+* Example of gnatcheck Usage::
@end menu
@node Format of the Report File
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 diagnostics 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 diagnostics 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
@group
pragma Annotate (gnatcheck, @i{exemption_control}, @i{Rule_Name}, [@i{justification}]);
-@i{exemption_control} ::= "Exempt_On" | "Exempt_Off"
+@i{exemption_control} ::= Exempt_On | Exempt_Off
@i{Rule_Name} ::= string_literal
delimited by an @code{exempt_on} and @code{exempt_off} annotation pair:
@smallexample @c ada
-pragma Annotate (gnatcheck, "Exempt_On", Rule_Name, "justification");
+pragma Annotate (gnatcheck, Exempt_On, Rule_Name, "justification");
-- source code section
-pragma Annotate (gnatcheck, "Exempt_Off", Rule_Name);
+pragma Annotate (gnatcheck, Exempt_Off, Rule_Name);
@end smallexample
@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
@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
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
* 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