From ee13bdc7cb8b37372563c0c0ad9482c1249a6f26 Mon Sep 17 00:00:00 2001 From: Sergey Rybin Date: Wed, 27 Jan 2010 11:58:53 +0000 Subject: [PATCH] gnat_rm.texi, [...]: Update gnatcheck doc. 2010-01-27 Sergey Rybin * gnat_rm.texi, gnat_ugn.texi: Update gnatcheck doc. From-SVN: r156279 --- gcc/ada/ChangeLog | 4 + gcc/ada/gnat_rm.texi | 21 ++++- gcc/ada/gnat_ugn.texi | 187 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 211 insertions(+), 1 deletion(-) diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 814961b7a31..9674a209777 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,7 @@ +2010-01-27 Sergey Rybin + + * gnat_rm.texi, gnat_ugn.texi: Update gnatcheck doc. + 2010-01-27 Robert Dewar * sinput.ads, sinput.adb (Sloc_Range): Applies to all nodes, formal diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi index 46823f9ebad..abfb4ee0634 100644 --- a/gcc/ada/gnat_rm.texi +++ b/gcc/ada/gnat_rm.texi @@ -16454,7 +16454,7 @@ package_spec ::= package_identifier ::= @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} | @code{Linker} | @code{Finder} | @code{Cross_Reference} | - @code{gnatls} | @code{IDE} | @code{Pretty_Printer} + @code{gnatls} | @code{IDE} | @code{Pretty_Printer} | @code{Check} @end smallexample @subsection Package Naming @@ -16775,6 +16775,25 @@ be called with the options specified by Default_Switches of its language, if defined. @end table +@subsection package Check + +@noindent +The attributes of package @code{Check} +specify the checking rule options to be used +when invoking the checking tool @command{gnatcheck}. +The following attributes apply to package @code{Check}: + +@table @code +@item Default_switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when calling @command{gnatcheck} on a source +written in that language. The first string in the range should always be +@code{"-rules"} to specify that all the other options belong to the +@code{-rules} section of the parameters of @command{gnatcheck} call. + +@end table + @subsection package Pretty_Printer @noindent diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index 9d35f8ec908..ab52d637c95 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/gcc/ada/gnat_ugn.texi @@ -492,6 +492,7 @@ Verifying Properties Using gnatcheck * Project-Wide Checks:: * Rule exemption:: * Predefined Rules:: +* Example of gnatcheck Usage:: Sample Bodies Using gnatstub @@ -12719,6 +12720,8 @@ case insensitive. The following package names are legal: @item @code{Cross_Reference} @item +@code{Check} +@item @code{Eliminate} @item @code{Pretty_Printer} @@ -14925,6 +14928,10 @@ package @code{Gnatstub} for command STUB @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^}) @@ -20736,6 +20743,7 @@ supplied. * Project-Wide Checks:: * Rule exemption:: * Predefined Rules:: +* Example of gnatcheck Usage:: @end menu @node Format of the Report File @@ -22933,6 +22941,185 @@ Only variable declarations, and not constant declarations, are checked. 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 -- 2.30.2