@c o
@c G N A T _ U G N o
@c o
-@c Copyright (C) 1992-2011, Free Software Foundation, Inc. o
+@c Copyright (C) 1992-2012, Free Software Foundation, Inc. o
@c o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@option{-gnatwd} (implicit dereferencing),
@option{-gnatwh} (hiding),
@option{-gnatw.h} (holes (gaps) in record layouts)
+@option{-gnatw.i} (overlapping actuals),
@option{-gnatwl} (elaboration warnings),
-@option{-gnatw.o} (warn on values set by out parameters ignored)
-and @option{-gnatwt} (tracking of deleted conditional code).
+@option{-gnatw.l} (inherited aspects),
+@option{-gnatw.o} (warn on values set by out parameters ignored),
+@option{-gnatwt} (tracking of deleted conditional code)
+and @option{-gnatw.u} (unordered enumeration),
All other optional warnings are turned on.
@item -gnatwA
@cindex @option{-gnatwA} (@command{gcc})
This switch suppresses all optional warning messages, see remaining list
in this section for details on optional warning messages that can be
-individually controlled.
+individually controlled. Note that unlike switch @option{-gnatws}, the
+use of switch @option{-gnatwA} does not suppress warnings that are
+normally given unconditionally and cannot be individually controlled
+(for example, the warning about a missing exit path in a function).
+Also, again unlike switch @option{-gnatws}, warnings suppressed by
+the use of switch @option{-gnatwA} can be individually turned back
+on. For example the use of switch @option{-gnatwA} followed by
+switch @option{-gnatwd} will suppress all optional warnings except
+the warnings for implicit dereferencing.
@item -gnatw.a
@emph{Activate warnings on failing assertions.}
@cindex @option{-gnatw.e} (@command{gcc})
@cindex Warnings, activate every optional warning
This switch activates all optional warnings, including those which
-are not activated by @code{-gnatwa}.
+are not activated by @code{-gnatwa}. The use of this switch is not
+recommended for normal use. If you turn this switch on, it is almost
+certain that you will get large numbers of useless warnings. The
+warnings that are excluded from @code{-gnatwa} are typically highly
+specialized warnings that are suitable for use only in code that has
+been specifically designed according to specialized coding rules.
@item -gnatwf
@emph{Activate warnings on unreferenced formals.}
See the section in this guide on elaboration checking for details on
when such pragmas should be used.
+@item -gnatw.l
+@emph{List inherited aspects.}
+@cindex @option{-gnatw.l} (@command{gcc})
+This switch causes the compiler to list inherited invariants,
+preconditions, and postconditions from Invariant'Class, Pre'Class, and
+Post'Class aspects. Also list inherited subtype predicates.
+These messages are not automatically turned on by the use of @option{-gnatwa}.
+
+@item -gnatw.L
+@emph{Suppress listing of inherited aspects.}
+@cindex @option{-gnatw.L} (@command{gcc})
+This switch suppresses listing of inherited aspects.
+
@item -gnatwm
@emph{Activate warnings on modified but unreferenced variables.}
@cindex @option{-gnatwm} (@command{gcc})
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.
+rather than x. In addition expressions of the form 2*x for small x
+generate a warning (the almost certainly accurate guess being that
+2**x was intended). The default is that these warnings are given.
@item -gnatw.M
@emph{Disable warnings on suspicious modulus values.}
@emph{Suppress all warnings.}
@cindex @option{-gnatws} (@command{gcc})
This switch completely suppresses the
-output of all warning messages from the GNAT front end.
-Note that it does not suppress warnings from the @command{gcc} back end.
+output of all warning messages from the GNAT front end, including
+both warnings that can be controlled by switches described in this
+section, and those that are normally given unconditionally. The
+effect of this suppress action can only be cancelled by a subsequent
+use of the switch @option{-gnatwn}.
+
+Note that switch @option{-gnatws} does not suppress
+warnings from the @command{gcc} back end.
To suppress these back end warnings as well, use the switch @option{-w}
in addition to @option{-gnatws}. Also this switch has no effect on the
handling of style check messages.
@cindex @option{-gnatwT} (@command{gcc})
This switch suppresses warnings for tracking of deleted conditional code.
+@item -gnatw.t
+@emph{Activate warnings on suspicious contracts.}
+@cindex @option{-gnatw.t} (@command{gcc})
+This switch activates warnings on suspicious postconditions (whether a
+pragma @code{Postcondition} or a @code{Post} aspect in Ada 2012). A
+function postcondition is suspicious when it does not mention the result
+of the function. A procedure postcondition is suspicious when it only
+refers to the pre-state of the procedure, because in that case it should
+rather be expressed as a precondition. The default is that such warnings
+are not generated. This warning can also be turned on using @option{-gnatwa}.
+
+@item -gnatw.T
+@emph{Suppress warnings on suspicious contracts.}
+@cindex @option{-gnatw.T} (@command{gcc})
+This switch suppresses warnings on suspicious postconditions.
+
@item -gnatwu
@emph{Activate warnings on unused entities.}
@cindex @option{-gnatwu} (@command{gcc})
which the type is declared, or its body or subunits.) Please refer to
the description of pragma @code{Ordered} in the
@cite{@value{EDITION} Reference Manual} for further details.
+The default is that such warnings are not generated.
+This warning is not automatically turned on by the use of @option{-gnatwa}.
@item -gnatw.U
@emph{Deactivate warnings on unordered enumeration types.}
A string of warning parameters can be used in the same parameter. For example:
@smallexample
--gnatwaLe
+-gnatwaGe
@end smallexample
@noindent
-will turn on all optional warnings except for elaboration pragma warnings,
+will turn on all optional warnings except for unrecognized pragma warnings,
and also specify that warnings should be treated as errors.
@end ifclear
+
When no switch @option{^-gnatw^/WARNINGS^} is used, this is equivalent to:
@table @option
@c !sort!
+@item -gnatwB
+@item -gnatw.b
@item -gnatwC
+@item -gnatw.C
@item -gnatwD
@item -gnatwF
@item -gnatwg
@item -gnatwH
@item -gnatwi
+@item -gnatw.I
@item -gnatwJ
@item -gnatwK
@item -gnatwL
+@item -gnatw.L
@item -gnatwM
+@item -gnatw.m
@item -gnatwn
@item -gnatwo
+@item -gnatw.O
@item -gnatwP
+@item -gnatw.P
+@item -gnatwq
@item -gnatwR
+@item -gnatw.R
+@item -gnatw.S
+@item -gnatwT
+@item -gnatw.T
@item -gnatwU
@item -gnatwv
-@item -gnatwz
+@item -gnatww
+@item -gnatw.W
@item -gnatwx
+@item -gnatw.X
+@item -gnatwy
+@item -gnatwz
@end table
@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.
+boolean constants. In all other cases @code{and then}/@code{or else} are
+required.
-@item ^c^COMMENTS^ (double space)
+@item ^c^COMMENTS^
@emph{Check comments, double space.}
Comments must meet the following set of rules:
@end smallexample
@end itemize
-@item ^C^COMMENTS1^ (single space)
+@item ^C^COMMENTS1^
@emph{Check comments, single space.}
This is identical to @code{^c^COMMENTS^} except that only one space
is required following the @code{--} of a comment instead of two.
in the source text.
@item ^g^GNAT^
-@emph{GNAT style mode}
+@emph{GNAT style mode.}
The set of style check switches is set to match that used by the GNAT sources.
This may be useful when developing code that is eventually intended to be
incorporated into GNAT. For further details, see GNAT sources.
containing all or part of the condition to be tested.
@item ^I^IN_MODE^
-@emph{check mode IN keywords}
+@emph{check mode IN keywords.}
Mode @code{in} (the default mode) is not
allowed to be given explicitly. @code{in out} is fine,
but not @code{in} on its own.
@end smallexample
@item ^Lnnn^MAX_NESTING=nnn^
-@emph{Set maximum nesting level}
+@emph{Set maximum nesting level.}
The maximum level of nesting of constructs (including subprograms, loops,
blocks, packages, and conditionals) may not exceed the given value
@option{nnn}. A value of zero disconnects this style check.
@code{Integer} and @code{ASCII.NUL}).
@item ^N^NONE^
-@emph{Turn off all style checks}
+@emph{Turn off all style checks.}
All style check options are turned off.
@item ^o^ORDERED_SUBPROGRAMS^
identifiers. The only requirement is for consistency of references
with declarations.
-@item ^S^STATEMENTS_AFTER_THEN_ELSE^
-@emph{Check no statements after THEN/ELSE.}
-No statements are allowed
-on the same line as a THEN or ELSE keyword following the
-keyword in an IF statement. OR ELSE and AND THEN are not affected,
-and a special exception allows a pragma to appear after ELSE.
-
@item ^s^SPECS^
@emph{Check separate specs.}
Separate declarations (``specs'') are required for subprograms (a
not required to have a separate declaration. This exception covers
the most frequent form of main program procedures.
+@item ^S^STATEMENTS_AFTER_THEN_ELSE^
+@emph{Check no statements after @code{then}/@code{else}.}
+No statements are allowed
+on the same line as a @code{then} or @code{else} keyword following the
+keyword in an @code{if} statement. @code{or else} and @code{and then} are not
+affected, and a special exception allows a pragma to appear after @code{else}.
+
@item ^t^TOKEN^
@emph{Check token spacing.}
The following token spacing rules are enforced:
@itemize @bullet
@item
-The keywords @code{@b{abs}} and @code{@b{not}} must be followed by a space.
+The keywords @code{abs} and @code{not} must be followed by a space.
@item
The token @code{=>} must be surrounded by spaces.
@item ^y^ALL_BUILTIN^
@emph{Set all standard style check options}
This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
-options enabled with the exception of @option{-gnatyo}, @option{-gnatyI},
-@option{-gnatyS}, @option{-gnatyLnnn},
-@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
+options enabled with the exception of @option{-gnatyB}, @option{-gnatyd},
+@option{-gnatyI}, @option{-gnatyLnnn}, @option{-gnatyo}, @option{-gnatyO},
+@option{-gnatyS}, @option{-gnatyu}, and @option{-gnatyx}.
@ifclear vms
@item -
The switch
@ifclear vms
@option{-gnaty} on its own (that is not
-followed by any letters or digits), then the effect is equivalent
-to the use of @option{-gnatyy}, as described above, that is all
+followed by any letters or digits) is equivalent
+to the use of @option{-gnatyy} as described above, that is all
built-in standard style check options are enabled.
@end ifclear
These implicit pragmas are still respected by the binder in
@option{^-p^/PESSIMISTIC_ELABORATION^} mode, so a
safe elaboration order is assured.
+
+Note that @option{^-p^/PESSIMISTIC_ELABORATION^} is not intended for
+production use; it is more for debugging/experimental use.
@end table
@node Output Control
@cindex @option{^-nt@var{x}^/TYPE_CASING^} (@command{gnatpp})
@item ^-neD^/TYPE_CASING=AS_DECLARED^
-Type and subtype name casing for defining occurrences are as they appear in
-the source file. Overrides ^-n^/NAME_CASING^ casing setting.
+Names introduced by type and subtype declarations are always
+cased as they appear in the declaration in the source file.
+Overrides ^-n^/NAME_CASING^ casing setting.
@item ^-ntU^/TYPE_CASING=UPPER_CASE^
-Type and subtype names are in upper case. Overrides ^-n^/NAME_CASING^ casing
-setting.
+Names introduced by type and subtype declarations are always in
+upper case. Overrides ^-n^/NAME_CASING^ casing setting.
@item ^-ntL^/TYPE_CASING=LOWER_CASE^
-Type and subtype names are in lower case. Overrides ^-n^/NAME_CASING^ casing
-setting.
+Names introduced by type and subtype declarations are always in
+lower case. Overrides ^-n^/NAME_CASING^ casing setting.
@item ^-ntM^/TYPE_CASING=MIXED_CASE^
-Type and subtype names are in mixed case. Overrides ^-n^/NAME_CASING^ casing
-setting.
+Names introduced by type and subtype declarations are always in
+mixed case. Overrides ^-n^/NAME_CASING^ casing setting.
@cindex @option{^-p@var{x}^/PRAGMA_CASING^} (@command{gnatpp})
@item ^-pL^/PRAGMA_CASING=LOWER_CASE^
imported from Ada units outside of the library. If other units are imported,
the binding phase will fail.
+@noindent
+It is also possible to build an encapsulated library where not only
+the code to elaborate and finalize the library is embedded but also
+ensuring that the library is linked only against static
+libraries. So an encapsulated library only depends on system
+libraries, all other code, including the GNAT runtime, is embedded. To
+build an encapsulated library the attribute
+@code{Library_Standalone} must be set to @code{encapsulated}:
+
+@smallexample @c projectfile
+@group
+ for Library_Dir use "lib_dir";
+ for Library_Name use "dummy";
+ for Library_Interface use ("int1", "int1.child");
+ for Library_Standalone use "encapsulated";
+@end group
+@end smallexample
+
+@noindent
+The default value for this attribute is @code{standard} in which case
+a stand-alone library is built.
+
The attribute @code{Library_Src_Dir} may be specified for a
Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
single string value. Its value must be the path (absolute or relative to the
@item filename
is the name of the source file containing the library unit package declaration
-for which a test package will be created. The file name may given with a path.
+for which a test package will be created. The file name may be given with a
+path.
-@item @samp{@var{gcc_switches}} is a list of switches for
+@item @samp{@var{gcc_switches}}
+is a list of switches for
@command{gcc}. These switches will be passed on to all compiler invocations
made by @command{gnatstub} to generate a set of ASIS trees. Here you can provide
@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
@command{gnattest} results can be found in two different places.
@itemize @bullet
-@item automatic harness
+@item automatic harness:
the harness code, which is located either in the harness-dir as specified on
the command line or in the project file. All of this code is generated
completely automatically and can be destroyed and regenerated at will. It is not
Note that you might need to specify the necessary values of scenario variables
when you are not using the AUnit defaults.
-@item actual unit test stubs
+@item actual unit test stubs:
a test stub for each visible subprogram is created in a separate file, if it
doesn't exist already. By default, those separate test files are located in a
"tests" directory that is created in the directory containing the source file
file my_unit.ads in directory src contains a visible subprogram Proc, then
the corresponding unit test will be found in file
src/tests/my_unit-tests-proc_<code>.adb. <code> is a signature encoding used to
-differentiate test names in cases of overloading.
+differentiate test names in case of overloading.
-Note that if the project already has both my_unit.ads and my_unit-tests.ads this
-will cause name a conflict with generated test package.
+Note that if the project already has both my_unit.ads and my_unit-tests.ads,
+this will cause a name conflict with the generated test package.
@end itemize
@node Switches for gnattest
The above will generate more complete bindings than a straight call without
the @option{-DXLIB_ILLEGAL_ACCESS} switch.
-In other cases, it is not possible to parse a header file in a stand alone
+In other cases, it is not possible to parse a header file in a stand-alone
manner, because other include files need to be included first. In this
case, the solution is to create a small header file including the needed
@code{#include} and possible @code{#define} directives. For example, to
the generic declaration explicitly indicates whether
or not such instantiations are permitted. If a generic formal parameter
has explicit unknown discriminants, indicated by using @code{(<>)} after the
-type name, then it can be instantiated with indefinite types, but no
+subtype name, then it can be instantiated with indefinite types, but no
stand-alone variables can be declared of this type. Any attempt to declare
such a variable will result in an illegality at the time the generic is
declared. If the @code{(<>)} notation is not used, then it is illegal
OSDN Git Service
