-\input texinfo @c -*-texinfo-*-
+f\input texinfo @c -*-texinfo-*-
@c %**start of header
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@setfilename gnat_ugn.info
@copying
-Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation,
+Copyright @copyright{} 1995-2009 Free Software Foundation,
Inc.
Permission is granted to copy, distribute and/or modify this document
* gnatcheck Rule Options::
* Adding the Results of Compiler Checks to gnatcheck Output::
* Project-Wide Checks::
+* Rule exemption::
* Predefined Rules::
Sample Bodies Using gnatstub
function Get_Value (Obj : Root) return int;
pragma Import (CPP, Get_Value);
- function Constructor return Root'Class;
+ function Constructor return Root;
pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev");
- function Constructor (v : Integer) return Root'Class;
+ function Constructor (v : Integer) return Root;
pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei");
- function Constructor (v, w : Integer) return Root'Class;
+ function Constructor (v, w : Integer) return Root;
pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii");
end Pkg_Root;
@end smallexample
On the Ada side the constructor is represented by a function (whose
name is arbitrary) that returns the classwide type corresponding to
-the imported C++ class.
+the imported C++ class. Although the constructor is described as a
+function, it is typically a procedure with an extra implicit argument
+(the object being initialized) at the implementation level. GNAT
+issues the appropriate call, whatever it is, to get the object
+properly initialized.
+Constructors can only appear in the following contexts:
+
+@itemize @bullet
+@item
+On the right side of an initialization of an object of type @var{T}.
+@item
+On the right side of an initialization of a record component of type @var{T}.
+@item
+In an Ada 2005 limited aggregate.
+@item
+In an Ada 2005 nested limited aggregate.
+@item
+In an Ada 2005 limited aggregate that initializes an object built in
+place by an extended return statement.
+@end itemize
+
+@noindent
In a declaration of an object whose type is a class imported from C++,
either the default C++ constructor is implicitly called by GNAT, or
else the required C++ constructor must be explicitly called in the
initialized by a C++ constructor, and the additional Ada components
of type DT are initialized by GNAT. The initialization of such an
object is done either by default, or by means of a function returning
-an aggregate of type DT, or by means of an extended aggregate.
+an aggregate of type DT, or by means of an extension aggregate.
@smallexample @c ada
Obj5 : DT;
Obj6 : DT := Function_Returning_DT (50);
- Obj7 : DT := (Constructor (30,40) with (C_Value => 50));
+ Obj7 : DT := (Constructor (30,40) with C_Value => 50);
@end smallexample
The declaration of @code{Obj5} invokes the default constructors: the
procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
pragma Import (C_Plus_Plus, Set_Owner);
- function New_Dog return Dog'Class;
+ function New_Dog return Dog;
pragma CPP_Constructor (New_Dog);
pragma Import (CPP, New_Dog, "_ZN3DogC2Ev");
end Animals;
@item -gnatB
@cindex @option{-gnatB} (@command{gcc})
-Assume no invalid (bad) values except for 'Valid attribute use.
+Assume no invalid (bad) values except for 'Valid attribute use
+(@pxref{Validity Checking}).
@item -gnatc
@cindex @option{-gnatc} (@command{gcc})
Check syntax and semantics only (no code generation attempted).
+@item -gnatC
+@cindex @option{-gnatC} (@command{gcc})
+Generate CodePeer information (no code generation attempted).
+This switch will generate an intermediate representation suitable for
+use by CodePeer (@file{.scil} files). This switch is not compatible with
+code generation (it will, among other things, disable some switches such
+as -gnatn, and enable others such as -gnata).
+
@item -gnatd
@cindex @option{-gnatd} (@command{gcc})
Specify debug options for the compiler. The string of characters after
@end ifclear
(@pxref{Integrated Preprocessing}).
+@item -gnateS
+@cindex @option{-gnateS} (@command{gcc})
+Generate SCO (Source Coverage Obligation) information in the ALI
+file. This information is used by advanced coverage tools. See
+unit @file{SCOs} in the compiler sources for details in files
+@file{scos.ads} and @file{scos.adb}.
+
@item -gnatE
@cindex @option{-gnatE} (@command{gcc})
Full dynamic elaboration checks.
@item -gnatV
@cindex @option{-gnatV} (@command{gcc})
-Control level of validity checking. See separate section describing
-this feature.
+Control level of validity checking (@pxref{Validity Checking}).
@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}@r{[},@dots{}@r{]})^
@cindex @option{^-gnatw^/WARNINGS^} (@command{gcc})
@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 (see description of @option{-gnatV}).
+as validity checking options (@pxref{Validity Checking}).
@end ifclear
@end itemize
@itemize @bullet
@item
-Full details on entities not available in high integrity mode
-@item
Details on possibly non-portable unchecked conversion
@item
List possible interpretations for ambiguous calls
This switch disables warnings for variables that are assigned or
initialized, but never read.
+@item -gnatw.m
+@emph{Activate warnings on suspicious modulus values.}
+@cindex @option{-gnatw.m} (@command{gcc})
+This switch activates warnings for modulus values that seem suspicious.
+The cases caught are where the size is the same as the modulus (e.g.
+a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
+with no size clause. The guess in both cases is that 2**x was intended
+rather than x. The default is that these warnings are given.
+
+@item -gnatw.M
+@emph{Disable warnings on suspicious modulus values.}
+@cindex @option{-gnatw.M} (@command{gcc})
+This switch disables warnings for suspicious modulus values.
+
@item -gnatwn
@emph{Set normal warnings mode.}
@cindex @option{-gnatwn} (@command{gcc})
@cindex @option{-gnatwR} (@command{gcc})
This switch suppresses warnings for redundant constructs.
+@item -gnatw.r
+@emph{Activate warnings for object renaming function.}
+@cindex @option{-gnatw.r} (@command{gcc})
+This switch activates warnings for an object renaming that renames a
+function call, which is equivalent to a constant declaration (as
+opposed to renaming the function itself). The default is that these
+warnings are given. This warning can also be turned on using
+@option{-gnatwa}.
+
+@item -gnatw.R
+@emph{Suppress warnings for object renaming function.}
+@cindex @option{-gnatwT} (@command{gcc})
+This switch suppresses warnings for object renaming function.
+
@item -gnatws
@emph{Suppress all warnings.}
@cindex @option{-gnatws} (@command{gcc})
@findex Validity Checking
@noindent
-The Ada Reference Manual has specific requirements for checking
-for invalid values. In particular, RM 13.9.1 requires that the
-evaluation of invalid values (for example from unchecked conversions),
-not result in erroneous execution. In GNAT, the result of such an
-evaluation in normal default mode is to either use the value
-unmodified, or to raise Constraint_Error in those cases where use
-of the unmodified value would cause erroneous execution. The cases
-where unmodified values might lead to erroneous execution are case
-statements (where a wild jump might result from an invalid value),
-and subscripts on the left hand side (where memory corruption could
-occur as a result of an invalid value).
+The Ada Reference Manual defines the concept of invalid values (see
+RM 13.9.1). The primary source of invalid values is uninitialized
+variables. A scalar variable that is left uninitialized may contain
+an invalid value; the concept of invalid does not apply to access or
+composite types.
+
+It is an error to read an invalid value, but the RM does not require
+run-time checks to detect such errors, except for some minimal
+checking to prevent erroneous execution (i.e. unpredictable
+behavior). This corresponds to the @option{-gnatVd} switch below,
+which is the default. For example, by default, if the expression of a
+case statement is invalid, it will raise Constraint_Error rather than
+causing a wild jump, and if an array index on the left-hand side of an
+assignment is invalid, it will raise Constraint_Error rather than
+overwriting an arbitrary memory location.
+
+The @option{-gnatVa} may be used to enable additional validity checks,
+which are not required by the RM. These checks are often very
+expensive (which is why the RM does not require them). These checks
+are useful in tracking down uninitialized variables, but they are
+not usually recommended for production builds.
+
+The other @option{-gnatV^@var{x}^^} switches below allow finer-grained
+control; you can enable whichever validity checks you desire. However,
+for most debugging purposes, @option{-gnatVa} is sufficient, and the
+default @option{-gnatVd} (i.e. standard Ada behavior) is usually
+sufficient for non-debugging use.
The @option{-gnatB} switch tells the compiler to assume that all
values are valid (that is, within their declared subtype range)
except in the context of a use of the Valid attribute. This means
the compiler can generate more efficient code, since the range
-of values is better known at compile time.
+of values is better known at compile time. However, an uninitialized
+variable can cause wild jumps and memory corruption in this mode.
-The @option{-gnatV^@var{x}^^} switch allows more control over the validity
-checking mode.
+The @option{-gnatV^@var{x}^^} switch allows control over the validity
+checking mode as described below.
@ifclear vms
The @code{x} argument is a string of letters that
indicate validity checks that are performed or not performed in addition
-to the default checks described above.
+to the default checks required by Ada as described above.
@end ifclear
@ifset vms
The options allowed for this qualifier
indicate validity checks that are performed or not performed in addition
-to the default checks described above.
+to the default checks required by Ada as described above.
@end ifset
@table @option
rule, together with h (no horizontal tabs), is to enforce a canonical format
for the use of blanks to separate source tokens.
+@item ^B^BOOLEAN_OPERATORS^
+@emph{Check Boolean operators.}
+The use of AND/OR operators is not permitted except in the cases of modular
+operands, array operands, and simple stand-alone boolean variables or
+boolean constants. In all other cases AND THEN/OR ELSE are required.
+
@item ^c^COMMENTS^
@emph{Check comments.}
Comments must meet the following set of rules:
@cindex Suppressing checks
@cindex Checks, suppressing
@findex Suppress
-Suppress all run-time checks as though @code{pragma Suppress (All_checks)}
-had been present in the source. Validity checks are also suppressed (in
+This switch causes the unit to be compiled
+as though @code{pragma Suppress (All_checks)}
+had been present in the source. Validity checks are also eliminated (in
other words @option{-gnatp} also implies @option{-gnatVn}.
Use this switch to improve the performance
of the code at the expense of safety in the presence of invalid data or
if checks are suppressed. In particular, if the compiler can prove
that a certain check will necessarily fail, it will generate code to
do an unconditional ``raise'', even if checks are suppressed. The
-compiler warns in this case.
+compiler warns in this case. Another case in which checks may not be
+eliminated is when they are embedded in certain run time routines such
+as math library routines.
Of course, run-time checks are omitted whenever the compiler can prove
that they will not fail, whether or not checks are suppressed.
Typically
these tools do the necessary compilations automatically, so you should
not have to specify this switch in normal operation.
+Note that the combination of switches @option{-gnatct}
+generates a tree in the form required by ASIS applications.
@item -gnatu
@cindex @option{-gnatu} (@command{gcc})
Ada_05
Ada_2005
Assertion_Policy
+ Assume_No_Invalid_Values
C_Pass_By_Copy
Check_Name
Check_Policy
Compile_Time_Warning
Compiler_Unit
Component_Alignment
+ Convention_Identifier
Debug_Policy
Detect_Blocking
Discard_Names
Elaboration_Checks
Eliminate
Extend_System
+ Extensions_Allowed
External_Name_Casing
Fast_Math
Favor_Top_Level
@node Importing Other Projects
@subsection Importing Other Projects
@cindex @code{ADA_PROJECT_PATH}
+@cindex @code{GPR_PROJECT_PATH}
@noindent
A compilation unit in a source file in one project may depend on compilation
The imported project file is in the same directory as the importing project
file, or
@item
-You have defined ^an environment variable^a logical name^
+You have defined one or two ^environment variables^logical names^
that includes the directory containing
-the needed project file. The syntax of @code{ADA_PROJECT_PATH} is the same as
+the needed project file. The syntax of @code{GPR_PROJECT_PATH} and
+@code{ADA_PROJECT_PATH} is the same as
the syntax of @code{ADA_INCLUDE_PATH} and @code{ADA_OBJECTS_PATH}: a list of
directory names separated by colons (semicolons on Windows).
@end itemize
@noindent
-Thus, if we define @code{ADA_PROJECT_PATH} to include @file{^/gui^[GUI]^} and
+Thus, if we define @code{ADA_PROJECT_PATH} or @code{GPR_PROJECT_PATH}
+to include @file{^/gui^[GUI]^} and
@file{^/comm^[COMM]^}, then our project file @file{app_proj.gpr} can be written
as follows:
@itemize @bullet
@item
-@code{abstract}: qualify a project with no sources. An abstract project must
-have a declaration specifying that there are no sources in the project, and,
-if it extends another project, the project it extends must also be a qualified
-abstract project.
+@code{abstract}: qualify a project with no sources. A qualified abstract
+project must either have no declaration of attributes @code{Source_Dirs},
+@code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
+@code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
+as empty. If it extends another project, the project it extends must also be a
+qualified abstract project.
@item
@code{standard}: a standard project is a non library project with sources.
an error to have several files with the same source file name.
Projects can be specified to have no Ada source
-files: the value of (@code{Source_Dirs} or @code{Source_Files} may be an empty
+files: the value of @code{Source_Dirs} or @code{Source_Files} may be an empty
list, or the @code{"Ada"} may be absent from @code{Languages}:
@smallexample @c projectfile
@node Importing Projects
@section Importing Projects
@cindex @code{ADA_PROJECT_PATH}
+@cindex @code{GPR_PROJECT_PATH}
@noindent
An immediate source of a project P may depend on source files that
@item
In between, all the directories referenced in the
-^environment variable^logical name^ @env{ADA_PROJECT_PATH} if it exists.
+^environment variables^logical names^ @env{GPR_PROJECT_PATH}
+and @env{ADA_PROJECT_PATH} if they exist, and in that order.
@end itemize
@noindent
will be a body if the longest suffix is @code{Body_Suffix ("Ada")} or a spec
if the longest suffix is @code{Spec_Suffix ("Ada")}.
+If the suffix does not start with a '.', a file with a name exactly equal
+to the suffix will also be part of the project (for instance if you define
+the suffix as @code{Makefile}, a file called @file{Makefile} will be part
+of the project. This is not interesting in general when using projects to
+compile. However, it might become useful when a project is also used to
+find the list of source files in an editor, like the GNAT Programming System
+(GPS).
+
If @code{Body_Suffix ("Ada")} is not specified, then the default is
@code{"^.adb^.ADB^"}.
@cindex @option{-nostdlib} (@command{gnatfind})
Do not look for library files in the system default directory.
+@item --ext=@var{extension}
+@cindex @option{--ext} (@command{gnatfind})
+Specify an alternate ali file extension. The default is @code{ali} and other
+extensions (e.g. @code{sli} for SPARK library files) may be specified via this
+switch. Note that if this switch overrides the default, which means that only
+the new extension will be considered.
+
@item --RTS=@var{rts-path}
@cindex @option{--RTS} (@command{gnatfind})
Specifies the default location of the runtime library. Same meaning as the
Do not place the keyword @code{is} on a separate line in a subprogram body in
case if the spec occupies more then one line.
+@cindex @option{^--separate-label^/SEPARATE_LABEL^} (@command{gnatpp})
+@item ^--separate-label^/SEPARATE_LABEL^
+Place statement label(s) on a separate line, with the following statement
+on the next line.
+
@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
Place the keyword @code{loop} in FOR and WHILE loop statements and the
@item ^-x^/XML^
Generate the XML output
+@cindex @option{^-xs^/XSD^} (@command{gnatmetric})
+@item ^-xs^/XSD^
+Generate the XML output and the XML schema file that describes the structure
+of the XML metric report, this schema is assigned to the XML file. The schema
+file has the same name as the XML output file with @file{.xml} suffix replaced
+with @file{.xsd}
+
@cindex @option{^-nt^/NO_TEXT^} (@command{gnatmetric})
@item ^-nt^/NO_TEXT^
Do not generate the output in text form (implies @option{^-x^/XML^})
@cindex @option{--no-lines@var{x}}
@end ifclear
-@item ^--lines-all^/LINE_COUNT_METRICS=ALL_ON^
+@item ^--lines-all^/LINE_COUNT_METRICS=ALL^
Report all the line metrics
-@item ^--no-lines-all^/LINE_COUNT_METRICS=ALL_OFF^
+@item ^--no-lines-all^/LINE_COUNT_METRICS=NONE^
Do not report any of line metrics
-@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES_ON^
+@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES^
Report the number of all lines
-@item ^--no-lines^/LINE_COUNT_METRICS=ALL_LINES_OFF^
+@item ^--no-lines^/LINE_COUNT_METRICS=NOALL_LINES^
Do not report the number of all lines
-@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES_ON^
+@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES^
Report the number of code lines
-@item ^--no-lines-code^/LINE_COUNT_METRICS=CODE_LINES_OFF^
+@item ^--no-lines-code^/LINE_COUNT_METRICS=NOCODE_LINES^
Do not report the number of code lines
-@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_ON^
+@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES^
Report the number of comment lines
-@item ^--no-lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_OFF^
+@item ^--no-lines-comment^/LINE_COUNT_METRICS=NOCOMMENT_LINES^
Do not report the number of comment lines
-@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_ON^
+@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES^
Report the number of code lines containing
end-of-line comments
-@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_OFF^
+@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=NOCODE_COMMENT_LINES^
Do not report the number of code lines containing
end-of-line comments
-@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_ON^
+@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE^
Report the comment percentage in the program text
-@item ^--no-lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_OFF^
+@item ^--no-lines-ratio^/LINE_COUNT_METRICS=NOCOMMENT_PERCENTAGE^
Do not report the comment percentage in the program text
-@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_ON^
+@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES^
Report the number of blank lines
-@item ^--no-lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_OFF^
+@item ^--no-lines-blank^/LINE_COUNT_METRICS=NOBLANK_LINES^
Do not report the number of blank lines
-@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_ON^
+@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES^
Report the average number of code lines in subprogram bodies, task bodies,
entry bodies and statement sequences in package bodies. The metric is computed
and reported for the whole set of processed Ada sources only.
-@item ^--no-lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_OFF^
+@item ^--no-lines-average^/LINE_COUNT_METRICS=NOAVERAGE_BODY_LINES^
Do not report the average number of code lines in subprogram bodies,
task bodies, entry bodies and statement sequences in package bodies.
@cindex @option{--no-syntax@var{x}} (@command{gnatmetric})
@end ifclear
-@item ^--syntax-all^/SYNTAX_METRICS=ALL_ON^
+@item ^--syntax-all^/SYNTAX_METRICS=ALL^
Report all the syntax metrics
-@item ^--no-syntax-all^/ALL_OFF^
+@item ^--no-syntax-all^/SYNTAX_METRICS=NONE^
Do not report any of syntax metrics
-@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS_ON^
+@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS^
Report the total number of declarations
-@item ^--no-declarations^/SYNTAX_METRICS=DECLARATIONS_OFF^
+@item ^--no-declarations^/SYNTAX_METRICS=NODECLARATIONS^
Do not report the total number of declarations
-@item ^--statements^/SYNTAX_METRICS=STATEMENTS_ON^
+@item ^--statements^/SYNTAX_METRICS=STATEMENTS^
Report the total number of statements
-@item ^--no-statements^/SYNTAX_METRICS=STATEMENTS_OFF^
+@item ^--no-statements^/SYNTAX_METRICS=NOSTATEMENTS^
Do not report the total number of statements
-@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_ON^
+@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS^
Report the number of public subprograms in a compilation unit
-@item ^--no-public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_OFF^
+@item ^--no-public-subprograms^/SYNTAX_METRICS=NOPUBLIC_SUBPROGRAMS^
Do not report the number of public subprograms in a compilation unit
-@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_ON^
+@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS^
Report the number of all the subprograms in a compilation unit
-@item ^--no-all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_OFF^
+@item ^--no-all-subprograms^/SYNTAX_METRICS=NOALL_SUBPROGRAMS^
Do not report the number of all the subprograms in a compilation unit
-@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES_ON^
+@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES^
Report the number of public types in a compilation unit
-@item ^--no-public-types^/SYNTAX_METRICS=PUBLIC_TYPES_OFF^
+@item ^--no-public-types^/SYNTAX_METRICS=NOPUBLIC_TYPES^
Do not report the number of public types in a compilation unit
-@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES_ON^
+@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES^
Report the number of all the types in a compilation unit
-@item ^--no-all-types^/SYNTAX_METRICS=ALL_TYPES_OFF^
+@item ^--no-all-types^/SYNTAX_METRICS=NOALL_TYPES^
Do not report the number of all the types in a compilation unit
-@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_ON^
+@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING^
Report the maximal program unit nesting level
@item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^
Do not report the maximal program unit nesting level
-@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_ON^
+@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING^
Report the maximal construct nesting level
-@item ^--no-construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_OFF^
+@item ^--no-construct-nesting^/SYNTAX_METRICS=NOCONSTRUCT_NESTING^
Do not report the maximal construct nesting level
@end table
@cindex @option{--no-complexity@var{x}}
@end ifclear
-@item ^--complexity-all^/COMPLEXITY_METRICS=ALL_ON^
+@item ^--complexity-all^/COMPLEXITY_METRICS=ALL^
Report all the complexity metrics
-@item ^--no-complexity-all^/COMPLEXITY_METRICS=ALL_OFF^
+@item ^--no-complexity-all^/COMPLEXITY_METRICS=NONE^
Do not report any of complexity metrics
-@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_ON^
+@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC^
Report the McCabe Cyclomatic Complexity
-@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_OFF^
+@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=NOCYCLOMATIC^
Do not report the McCabe Cyclomatic Complexity
-@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_ON^
+@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL^
Report the Essential Complexity
-@item ^--no-complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_OFF^
+@item ^--no-complexity-essential^/COMPLEXITY_METRICS=NOESSENTIAL^
Do not report the Essential Complexity
@item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^
Report maximal loop nesting level
-@item ^--no-loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_OFF^
+@item ^--no-loop-nesting^/COMPLEXITY_METRICS=NOLOOP_NESTING^
Do not report maximal loop nesting level
-@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_ON^
+@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY^
Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
task bodies, entry bodies and statement sequences in package bodies.
The metric is computed and reported for whole set of processed Ada sources
only.
-@item ^--no-complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_OFF^
+@item ^--no-complexity-average^/COMPLEXITY_METRICS=NOAVERAGE_COMPLEXITY^
Do not report the average McCabe Cyclomatic Complexity for all the subprogram
bodies, task bodies, entry bodies and statement sequences in package bodies
Do not consider @code{exit} statements as @code{goto}s when
computing Essential Complexity
+@item ^--extra-exit-points^/EXTRA_EXIT_POINTS^
+Report the extra exit points for subprogram bodies. As an exit point, this
+metric counts @code{return} statements and raise statements in case when the
+raised exception is not handled in the same body. In case of a function this
+metric subtracts 1 from the number of exit points, because a function body
+must contain at least one @code{return} statement.
+
+@item ^--no-extra-exit-points^/NOEXTRA_EXIT_POINTS^
+Do not report the extra exit points for subprogram bodies
@end table
a library generic package) that defines a tagged or an interface type,
together with all its descendant (generic) packages that define tagged
or interface types. For any package counted as a class,
-its body (if any) is considered
-together with its spec when counting the dependencies. For dependencies
+its body and subunits (if any) are considered
+together with its spec when counting the dependencies, and coupling
+metrics are reported for spec units only. For dependencies
between classes, the Ada semantic dependencies are considered.
For coupling metrics, only dependencies on units that are considered as
classes, are considered.
@cindex @option{/COUPLING_METRICS} (@command{gnatmetric})
@end ifset
-@item ^--coupling-all^/COUPLING_METRICS=ALL_ON^
+@item ^--coupling-all^/COUPLING_METRICS=ALL^
Report all the coupling metrics
-@item ^--no-coupling-all^/COUPLING_METRICS=ALL_OFF^
+@item ^--no-coupling-all^/COUPLING_METRICS=NONE^
Do not report any of metrics
-@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_ON^
+@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT^
Report package efferent coupling
-@item ^--no-package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_OFF^
+@item ^--no-package-efferent-coupling^/COUPLING_METRICS=NOPACKAGE_EFFERENT^
Do not report package efferent coupling
-@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_ON^
+@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT^
Report package afferent coupling
-@item ^--no-package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_OFF^
+@item ^--no-package-afferent-coupling^/COUPLING_METRICS=NOPACKAGE_AFFERENT^
Do not report package afferent coupling
-@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_ON^
+@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT^
Report category efferent coupling
-@item ^--no-category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_OFF^
+@item ^--no-category-efferent-coupling^/COUPLING_METRICS=NOCATEGORY_EFFERENT^
Do not report category efferent coupling
-@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_ON^
+@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT^
Report category afferent coupling
-@item ^--no-category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_OFF^
+@item ^--no-category-afferent-coupling^/COUPLING_METRICS=NOCATEGORY_AFFERENT^
Do not report category afferent coupling
@end table
All compilation units comprising an application, including those in a library,
need to be elaborated in an order partially defined by Ada's semantics. GNAT
computes the elaboration order from the @file{ALI} files and this is why they
-constitute a mandatory part of GNAT libraries. Except in the case of
-@emph{stand-alone libraries}, where a specific library elaboration routine is
-produced independently of the application(s) using the library.
+constitute a mandatory part of GNAT libraries.
+@emph{Stand-alone libraries} are the exception to this rule because a specific
+library elaboration routine is produced independently of the application(s)
+using the library.
@node General Ada Libraries
@section General Ada Libraries
@node Installing a library
@subsection Installing a library
@cindex @code{ADA_PROJECT_PATH}
+@cindex @code{GPR_PROJECT_PATH}
@noindent
If you use project files, library installation is part of the library build
files and libraries in the directories mentioned in the project file. For
convenience, the user's library project file should be installed in a location
that will be searched automatically by the GNAT
-builder. These are the directories referenced in the @env{ADA_PROJECT_PATH}
+builder. These are the directories referenced in the @env{GPR_PROJECT_PATH}
environment variable (@pxref{Importing Projects}), and also the default GNAT
library location that can be queried with @command{gnatls -v} and is usually of
the form $gnat_install_root/lib/gnat.
* gnatcheck Rule Options::
* Adding the Results of Compiler Checks to gnatcheck Output::
* Project-Wide Checks::
+* Rule exemption::
* Predefined Rules::
@end menu
directory, @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 paarmeters
+of the @command{gnatcheck} invocation;
+@item the list of enabled rules;
+@item the total number of detected violations;
+@item list of source files for that rule violations have been detected;
+@item list of source files with no violations detected;
@end itemize
@node General gnatcheck Switches
of this construct in the generic unit to the place where this unit is
instantiated.
+@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.
+
@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,
Include the section containing diagnoses ordered by files and then by rules
in the report file
+@cindex @option{^-t^/TIME^} (@command{gnatcheck})
+@item ^-t^/TIME^
+Print out execution time.
+
@cindex @option{^-v^/VERBOSE^} (@command{gnatcheck})
@item ^-v^/VERBOSE^
Verbose mode; @command{gnatcheck} generates version information and then
a trace of sources being processed.
-
@cindex @option{^-o ^/OUTPUT^} (@command{gnatcheck})
@item ^-o ^/OUTPUT=^@var{report_file}
Set name of report file file to @var{report_file} .
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}).
+@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
+@code{-gnatyO} style check option.
@item Warnings
To record compiler warnings (@pxref{Warning Message Control}), use the rule
@end smallexample
+@node Rule exemption
+@section Rule exemption
+@cindex Rule exemption (for @command{gnatcheck})
+
+@noindent
+@command{gnatcheck} can be used to inforce a coding standard. It may be
+appropriate, in some circumstances, to accept violations of the coding
+standard. In such a case, it is a good idea to justify the violation within
+the sources themselves. It makes it possible to maintain the justification
+for such violations along with the sources containing them.
+@command{gnatcheck} supports such justified violations with the notion of
+``exemption'' covering a specific source code section. Usually,
+@command{gnatcheck} issues rule violation messages both on @file{stderr}
+and in a report file. Exempted violations are not reported at all on
+@file{stderr} so that users using @command{gnatcheck} in interactive mode
+(e.g. in its GPS interface) do not need to pay attention to known and
+justified violations. The @command{gnatcheck} report includes exempted
+violations in a special section along with their justification.
+
+@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 parameter is
+``gnatcheck''. Here is the syntax of @command{gnatcheck} annotations:
+
+@smallexample @c ada
+pragma Annotate (gnatcheck, exemption_control, Rule_Name, [justification]);
+
+exemption_control ::= "Exempt_On" | "Exempt_Off"
+
+Rule_Name ::= string_literal
+
+justification ::= string_literal
+
+@end smallexample
+
+@noindent
+When a @command{gnatcheck} annotatation has more then four parameters,
+@command{gnatcheck} issues a warning and ignore additional parameters.
+If the additional parameters do not follow the syntax above,
+@command{gnatcheck} emits a warning and ignores the annotation.
+
+@code{Rule_Name} should be the name of some existing @command{gnatcheck} rule.
+If this is not the case, the 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 silently.
+
+A source code section where an exemption is active for a given rule starts with
+an extempt_on annotation and terminates with an exempt_off one:
+
+@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 in order to create a properly formed exempted source
+code section;
+
+@item
+exempted source code sections are only based on the source location of the
+annotations. Any source construct having a source location in 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. It is not allowed
+to create nested or intersecting source code sections for the same rule;
+
+@item
+malformed exempted source code sections are reported by a warning and
+the corresponding rule exemption is 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}. This allow proper
+maintenance of exempted source code sections;
+
+@item
+if an exempted source code section reaches the end of the compilation unit
+source and there is no @code{Annotate} pragma closing this section, then the
+exemption for the given rule is turned off and a warning is issued.
+
+@end itemize
+
+
@node Predefined Rules
@section Predefined Rules
@cindex Predefined rules (for @command{gnatcheck})
@ignore
* Ceiling_Violations::
@end ignore
+* Complex_Inlined_Subprograms::
* Controlled_Type_Declarations::
* Declarations_In_Blocks::
+* Deep_Inheritance_Hierarchies::
+* Deeply_Nested_Generics::
+* Deeply_Nested_Inlining::
+@ignore
+* Deeply_Nested_Local_Inlining::
+@end ignore
* Default_Parameters::
+* Direct_Calls_To_Primitives::
* Discriminated_Records::
* Enumeration_Ranges_In_CASE_Statements::
* Exceptions_As_Control_Flow::
+* Exits_From_Conditional_Loops::
* EXIT_Statements_With_No_Loop_Name::
* Expanded_Loop_Exit_Names::
* Explicit_Full_Discrete_Ranges::
* Float_Equality_Checks::
+* Forbidden_Attributes::
* Forbidden_Pragmas::
* Function_Style_Procedures::
* Generics_In_Subprograms::
* Improperly_Called_Protected_Entries::
@end ignore
* Metrics::
+* Misnamed_Controlling_Parameters::
* Misnamed_Identifiers::
* Multiple_Entries_In_Protected_Definitions::
* Name_Clashes::
* Side_Effect_Functions::
@end ignore
* Slices::
+* Too_Many_Parents::
* Unassigned_OUT_Parameters::
* Uncommented_BEGIN_In_Package_Bodies::
+* Unconditional_Exits::
* Unconstrained_Array_Returns::
* Universal_Ranges::
* Unnamed_Blocks_And_Loops::
* Unused_Subprograms::
@end ignore
* USE_PACKAGE_Clauses::
+* Visible_Components::
* Volatile_Objects_Without_Address_Clauses::
@end menu
@ignore
@node Ceiling_Violations
-@subsection @code{Ceiling_Violations} (under construction, GLOBAL)
+@subsection @code{Ceiling5_Violations} (under construction, GLOBAL)
@cindex @code{Ceiling_Violations} rule (for @command{gnatcheck})
@noindent
This rule has no parameters.
+@node Complex_Inlined_Subprograms
+@subsection @code{Complex_Inlined_Subprograms}
+@cindex @code{Complex_Inlined_Subprograms} rule (for @command{gnatcheck})
+
+@noindent
+Flags a subprogram (or generic subprogram) if
+pragma Inline is applied to the subprogram and at least one of the following
+conditions is met:
+
+@itemize @bullet
+@item
+it contains at least one complex declaration such as a subprogram body,
+package, task, protected declaration, or a generic instantiation
+(except instantiation of @code{Ada.Unchecked_Conversion});
+
+@item
+it contains at least one complex statement such as a loop, a case
+or a if statement, or a short circuit control form;
+
+@item
+the number of statements exceeds
+a value specified by the @option{N} rule parameter;
+@end itemize
+
+@noindent
+This rule has the following (mandatory) parameter for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximum allowed total number of statements
+in the subprogram body.
+@end table
+
@node Declarations_In_Blocks
@subsection @code{Declarations_In_Blocks}
This rule has no parameters.
+@node Deep_Inheritance_Hierarchies
+@subsection @code{Deep_Inheritance_Hierarchies}
+@cindex @code{Deep_Inheritance_Hierarchies} rule (for @command{gnatcheck})
+
+@noindent
+Flags a tagged derived type declaration or an interface type declaration if
+its depth (in its inheritance
+hierarchy) exceeds the value specified by the @option{N} rule parameter.
+
+The inheritance depth of a tagged type or interface type is defined as 0 for
+a type with no parent and no progenitor, and otherwise as 1 + max of the
+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
+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
+hierarchy. If the rule parameter is set to -1, the rule flags all the declarations
+of tagged and interface types.
+@end table
+
+
+@node Deeply_Nested_Generics
+@subsection @code{Deeply_Nested_Generics}
+@cindex @code{Deeply_Nested_Generics} rule (for @command{gnatcheck})
+
+@noindent
+Flags a generic declaration nested in another generic declaration if
+the nesting level of the inner generic exceeds
+a value specified by the @option{N} rule parameter.
+The nesting level is the number of generic declaratons that enclose the given
+(generic) declaration. Formal packages are not flagged by this rule.
+
+This rule has the following (mandatory) parameters for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximal allowed nesting level
+for a generic declaration.
+@end table
+
+@node Deeply_Nested_Inlining
+@subsection @code{Deeply_Nested_Inlining}
+@cindex @code{Deeply_Nested_Inlining} rule (for @command{gnatcheck})
+
+@noindent
+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 requires the global analysis of all the compilation units that
+are @command{gnatcheck} arguments; such analysis may affect the tool's
+performance.
+
+This rule has the following (mandatory) parameter for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximal allowed level of nested inlining.
+@end table
+
+
+@ignore
+@node Deeply_Nested_Local_Inlining
+@subsection @code{Deeply_Nested_Local_Inlining}
+@cindex @code{Deeply_Nested_Local_Inlining} rule (for @command{gnatcheck})
+
+@noindent
+Flags a subprogram body if a pragma @code{Inline} is applied to the
+corresponding subprogram (or generic subprogram) and the body contains a call
+to another inlined subprogram that results in nested inlining with nesting
+depth more then a value specified by the @option{N} rule parameter.
+This rule is similar to @code{Deeply_Nested_Inlining} rule, but it
+assumes that calls to subprograms in
+with'ed units are not inlided, so all the analysis of the depth of inlining is
+limited by the compilation unit where the subprogram body is located and the
+units it depends semantically upon. Such analysis may be usefull for the case
+when neiter @option{-gnatn} nor @option{-gnatN} option is used when building
+the executable.
+
+This rule has the following (mandatory) parameters for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximal allowed level of nested inlining.
+@end table
+
+@end ignore
+
@node Default_Parameters
@subsection @code{Default_Parameters}
@cindex @code{Default_Parameters} rule (for @command{gnatcheck})
This rule has no parameters.
+@node Direct_Calls_To_Primitives
+@subsection @code{Direct_Calls_To_Primitives}
+@cindex @code{Direct_Calls_To_Primitives} rule (for @command{gnatcheck})
+
+@noindent
+Flags any non-dispatching call to a dispatching primitive operation, except
+for the common idiom where a primitive subprogram for a tagged type
+directly calls the same primitive subprogram of the type's immediate ancestor.
+
+This rule has no parameters.
+
+
@node Discriminated_Records
@subsection @code{Discriminated_Records}
@cindex @code{Discriminated_Records} rule (for @command{gnatcheck})
The rule has no parameters.
+@node Exits_From_Conditional_Loops
+@subsection @code{Exits_From_Conditional_Loops}
+@cindex @code{Exits_From_Conditional_Loops} (for @command{gnatcheck})
+
+@noindent
+Flag any exit statement if it transfers the control out of a @code{for} loop
+or a @code{while} loop. This includes cases when the @code{exit} statement
+applies to a @code{FOR} or @code{while} loop, and cases when it is enclosed
+in some @code{for} or @code{while} loop, but transfers the control from some
+outer (inconditional) @code{loop} statement.
+
+The rule has no parameters.
+
+
@node EXIT_Statements_With_No_Loop_Name
@subsection @code{EXIT_Statements_With_No_Loop_Name}
@cindex @code{EXIT_Statements_With_No_Loop_Name} (for @command{gnatcheck})
This rule has no parameters.
+@node Forbidden_Attributes
+@subsection @code{Forbidden_Attributes}
+@cindex @code{Forbidden_Attributes} rule (for @command{gnatcheck})
+
+@noindent
+Flag each use of the specified attributes. The attributes to be detected are
+named in the rule's parameters.
+
+This rule has the following parameters:
+
+@itemize @bullet
+@item For the @option{+R} option
+
+@table @asis
+@item @emph{Attribute_Designator}
+Adds the specified attribute to the set of attributes to be detected and sets
+the detection checks for all the specified attributes ON.
+If @emph{Attribute_Designator}
+does not denote any attribute defined in the Ada standard
+or in
+@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference
+Manual}, it is treated as the name of unknown attribute.
+
+@item @code{GNAT}
+All the GNAT-specific attributes are detected; this sets
+the detection checks for all the specified attributes ON.
+
+@item @code{ALL}
+All attributes are detected; this sets the rule ON.
+@end table
+
+@item For the @option{-R} option
+@table @asis
+@item @emph{Attribute_Designator}
+Removes the specified attribute from the set of attributes to be
+detected without affecting detection checks for
+other attributes. If @emph{Attribute_Designator} does not correspond to any
+attribute defined in the Ada standard or in
+@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference Manual},
+this option is treated as turning OFF detection of all unknown attributes.
+
+@item GNAT
+Turn OFF detection of all GNAT-specific attributes
+
+@item ALL
+Clear the list of the attributes to be detected and
+turn the rule OFF.
+@end table
+@end itemize
+
+@noindent
+Parameters are not case sensitive. If @emph{Attribute_Designator} does not
+have the syntax of an Ada identifier and therefore can not be considered as a
+(part of an) attribute designator, a diagnostic message is generated and the
+corresponding parameter is ignored. (If an attribute allows a static
+expression to be a part of the attribute designator, this expression is
+ignored by this rule.)
+
+When more then one parameter is given in the same rule option, the parameters
+must be separated by commas.
+
+If more then one option for this rule is specified for the gnatcheck call, a
+new option overrides the previous one(s).
+
+The @option{+R} option with no parameters turns the rule ON, with the set of
+attributes to be detected defined by the previous rule options.
+(By default this set is empty, so if the only option specified for the rule is
+@option{+RForbidden_Attributes} (with
+no parameter), then the rule is enabled, but it does not detect anything).
+The @option{-R} option with no parameter turns the rule OFF, but it does not
+affect the set of attributes to be detected.
+
+
@node Forbidden_Pragmas
@subsection @code{Forbidden_Pragmas}
@cindex @code{Forbidden_Pragmas} rule (for @command{gnatcheck})
-RMetrics_Cyclomatic_Complexity
@end smallexample
+
+@node Misnamed_Controlling_Parameters
+@subsection @code{Misnamed_Controlling_Parameters}
+@cindex @code{Misnamed_Controlling_Parameters} rule (for @command{gnatcheck})
+
+@noindent
+Flags a declaration of a dispatching operation, if the first parameter is
+not a controlling one and its name is not @code{This} (the check for
+parameter name is not case-sensitive). Declarations of dispatching functions
+with controlling result and no controlling parameter are never flagged.
+
+A subprogram body declaration, subprogram renaming declaration or subprogram
+body stub is flagged only if it is not a completion of a prior subprogram
+declaration.
+
+This rule has no parameters.
+
+
+
@node Misnamed_Identifiers
@subsection @code{Misnamed_Identifiers}
@cindex @code{Misnamed_Identifiers} rule (for @command{gnatcheck})
type declarations
@item
+subtype declarations
+
+@item
constant declarations (but not number declarations)
@item
@end itemize
@noindent
-For a private or incomplete type declaration the following checks are
-made for the defining name suffix:
+Defining identifiers from incomplete type declarations are never flagged.
-@itemize @bullet
-@item
-For an incomplete type declaration: if the corresponding full type
-declaration is available, the defining identifier from the full type
-declaration is checked, but the defining identifier from the incomplete type
-declaration is not; otherwise the defining identifier from the incomplete
-type declaration is checked against the suffix specified for type
-declarations.
-
-@item
-For a private type declaration (including private extensions), the defining
+For a private type declaration (including private extensions), the defining
identifier from the private type declaration is checked against the type
suffix (even if the corresponding full declaration is an access type
declaration), and the defining identifier from the corresponding full type
declaration is not checked.
-@end itemize
@noindent
For a deferred constant, the defining name in the corresponding full constant
Specifies the suffix for an access type name. If
this parameter is set, it overrides for access
types the suffix set by the @code{Type_Suffix} parameter.
+For access types, @emph{string} may have the following format:
+@emph{suffix1(suffix2)}. That means that an access type name
+should have the @emph{suffix1} suffix except for the case when
+the designated type is also an access type, in this case the
+type name should have the @emph{suffix1 & suffix2} suffix.
+
+@item Class_Access_Suffix=@emph{string}
+Specifies the suffix for the name of an access type that points to some class-wide
+type. If this parameter is set, it overrides for such access
+types the suffix set by the @code{Type_Suffix} or @code{Access_Suffix}
+parameter.
+
+@item Class_Subtype_Suffix=@emph{string}
+Specifies the suffix for the name of a subtype that denotes a class-wide type.
@item Constant_Suffix=@emph{string}
Specifies the suffix for a constant name.
If @code{Type_Suffix} is set, access type names are
checked as ordinary type names.
+@item Class_Access_Suffix
+Removes the suffix specified for access types pointing to class-wide
+type. This disables specific checks for names of access types pointing to
+class-wide types but does not disable any other checks for this rule.
+If @code{Type_Suffix} is set, access type names are
+checked as ordinary type names. If @code{Access_Suffix} is set, these
+access types are checked as any other access type name.
+
+@item Class_Subtype_Suffix=@emph{string}
+Removes the suffix specified for subtype names.
+This disables checks for subtype names but
+does not disable any other checks for this rule.
+
@item Constant_Suffix
Removes the suffix specified for constants. This
disables checks for constant names but does not
This rule has no parameters.
+@node Too_Many_Parents
+@subsection @code{Too_Many_Parents}
+@cindex @code{Too_Many_Parents} rule (for @command{gnatcheck})
+
+@noindent
+Flags any type declaration, single task declaration or single protected
+declaration that has more then @option{N} parents, @option{N} is a parameter
+of the rule.
+A parent here is either a (sub)type denoted by the subtype mark from the
+parent_subtype_indication (in case of a derived type declaration), or
+any of the progenitors from the interface list, if any.
+
+This rule has the following (mandatory) parameters for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximal allowed number of parents.
+@end table
+
+
@node Unassigned_OUT_Parameters
@subsection @code{Unassigned_OUT_Parameters}
@cindex @code{Unassigned_OUT_Parameters} rule (for @command{gnatcheck})
This rule has no parameters.
+@node Unconditional_Exits
+@subsection @code{Unconditional_Exits}
+@cindex @code{Unconditional_Exits} rule (for @command{gnatcheck})
+
+@noindent
+Flag unconditional @code{exit} statements.
+
+This rule has no parameters.
@node Unconstrained_Array_Returns
@subsection @code{Unconstrained_Array_Returns}
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 Visible_Components
+@subsection @code{Visible_Components}
+@cindex @code{Visible_Components} rule (for @command{gnatcheck})
+
+@noindent
+Flags all the type declarations located in the visible part of a library
+package or a library generic package that can declare a visible component. A
+type is considered as declaring a visible component if it contains a record
+definition by its own or as a part of a record extension. Type declaration is
+flagged even if it contains a record definition that defines no components.
+
+Declarations located in private parts of local (generic) packages are not
+flagged. Declarations in private packages are not flagged.
+
+This rule has no parameters.
+
@node Volatile_Objects_Without_Address_Clauses
@subsection @code{Volatile_Objects_Without_Address_Clauses}
Avoind raising PROGRAM_ERROR in the generated bodies of program unit stubs.
This is not always possible for function stubs.
+@item ^--no-local-header^/NO_LOCAL_HEADER^
+@cindex @option{^--no-local-header^/NO_LOCAL_HEADER^} (@command{gnatstub})
+Do not place local comment header with unit name before body stub for a
+unit.
+
@item ^-o ^/BODY=^@var{body-name}
@cindex @option{^-o^/BODY^} (@command{gnatstub})
Body file name. This should be set if the argument file name does not
(this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");
- function New_Dog return Dog'Class;
+ function New_Dog return Dog;
pragma CPP_Constructor (New_Dog);
pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
end;
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
@command{gnatmake}) command, or by the use of the configuration pragma:
@smallexample @c ada
-pragma Elaboration_Checks (RM);
+pragma Elaboration_Checks (DYNAMIC);
@end smallexample
@noindent
OSDN Git Service
