1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
========================================================
GCH USERS GUIDE
===============
version 07
-- Copyright (c) 1999, Vitali Sh.Kaufman. --
-- --
-- Gch is distributed as free software; that is with full sources --
-- and in the hope that it will be useful, but WITHOUT ANY WARRANTY; --
-- without even the implied warranty of MERCHANTABILITY or FITNESS --
-- FOR A PARTICULAR PURPOSE. You can freely copy, modify and redistribute --
-- this software, provided that full sources are available for the version --
-- being distribute (original and modified), and for a modified version, --
-- any changes that you have made are clearly indicated. --
-- --
-- Gch was developed by Vitali Sh. Kaufman using a prototype --
-- and consultations by Sergey I. Rybin. --
------------------------------------------------------------------------------
Contents
1. What is gch?
2. How it works?
3. Installing gch
4. gch command line
5. Using gch under Windows 95/NT/98
6. Adjustment of gch
7. Current limitations and future plans
8. Related information
9. Submitting comments and bug reports
------------------------------------------------------------------------------
1. What is gch?
------------
gch (from Gnat CHecker) is a Ada rule-checking tool based on the ASIS
implementation for GNAT. It was developed and checked with the public version
of the GNAT/ASIS technology 3.11p. The tool checks an Ada source against a
given set of rules. When a violation of some rule is detected, gch generates
the corresponding GNAT-style diagnostic message.
From the users' viewpoint, gch can be used as a stand-alone rule-checking tool
and as the GNAT compiler with a set of additional compile-time checks
(depending on the options set, gch may create an object file for the source
file being checked in case if no rule violation is detected).
The current version of gch checks a set of rules from the Ada 95 Quality and
Style document (see the file named rules.ini for the list of rules checked by
the current version of gch; Rule_0 and Rule_1 are not from the document).
This version is a kind of working prototype aimed at demonstrating the idea
of ASIS-based rule checker for Ada programs.
In future versions we are going to extend the set of rules checked by gch and
to provide some means for adding user-defined rule checks.
The file named gnat_tests.txt contains an output of checking all Ada sources
from gnat_3.11p-src by the gch (using Gnat_Mode, Hide_Rejected_Files,
Show_Global_Statistics and not Verbose_Mode of diagnostics,
Rule_0 and Rule_1 disabled). It takes nearly 15 min on Pentium II 260 MHz, 64MB.
2. How it works?
------------
As any ASIS application built on top of ASIS-for-GNAT, gch needs a tree file
to operate on. In a default mode it first create an ASIS Context in a mode that
allows to create trees "on-the-fly", and then it runs the ASIS-based checker
to process the argument source. ASIS calls GNAT to compile the source to
create a tree when needed. If gch is called for a group of the Ada sources by
using a wild-card as the file name, these sources are processed one after another
inside the same ASIS Context.
If an argument source is not a legal Aga unit, or something wrong happen during
the compilation, all the GNAT diagnostic messages generated when creating the tree
are sent to stderr. In this case no tree is created, and therefore, the ASIS-based
rule-checking part of gch is not run.
3. Installing gch
--------------
gch is distributed in the source form. You can download it as gch.tar.gz (for Unix)
or gch.zip (for Windows 95/98/NT) from http://www.kolumbus.fi/vitali.kaufman/gch.
To install gch, you have to create unpack of one of these archives and the
executable for its driver subprogram Gch.Driver (files gch-driver.ads,
gch-driver.adb). gch is an ASIS application, so to create this executable,
you need ASIS-for-GNAT installed on your machine. The current version of
gch has been developed and tested with the public version of the GNAT/ASIS
technology 3.11p.
After creating the executable for gch, you may put it and the gch
configuration files gch.ini and rules.ini somewhere on your path.
Supposing that ASIS-for-GNAT is installed as an Ada library and that you
are in the directory where gch sources are unpacked, to create the
executable for gch (named also gch), you should call gnatmake like this:
gnatmake -o gch gch-driver.adb -largs -lasis -lgnat
Under Windows 95/98/NT you can use also the file COMPILE.bat to create the
executable for gch, the file CHECK_ALL.bat to check all files of the Tests
sub-directory, the file CLEAN.bat to remove all tree and ali files from the
sub-directory, and files TEST-*.bat to run some simple tests.
For Windows 95/98/NT users it is recommended to install gch into default
C:\asis\gch location, since the file COMPILE.bat compilation of the GCH
source files and all prepared tests contain the default setting of the PATH.
They set also the ADA_INCLUDE_PATH and ADA_OBJECTS_PATH as C:\local\asis.
To compile the GCH Ada source files under Windows 95/98/NT, just double click
COMPILE.bat. The GCH source files from gch directory will be compiled, binded
and linked, the file gch-driver.exe and other appropriate files will be placed
into gch/Tests directory. Then the file test_comp.adb will be checked by
gch-driver.exe providing output into RESULT.txt.
The RESULT.txt should be as follows.
--------------------------------------------------------------
test_comp.adb:15:4:explicitly raised predefined exception [Q&S 4.3.1(10)]
test_comp.adb:13:4:named parameter association recommended [Q&S 5.2.2]
--------------------------------------------------------------
No error messages should be generated by GNAT for this compilation except of
the following possible warning (please ignore it).
-----------------
IMPORTANT NOTICE:
This version of GNAT is unsupported and comes with absolutely no warranty.
If you intend to evaluate or use GNAT for building commercial applications,
please consult http://www.gnat.com/ for information
on the GNAT Professional product line.
----------------
See ASIS-for-GNAT documentation for more details concerning using the ASIS
implementation for GNAT and creating executables for ASIS applications.
4. gch command line
----------------
The current version of gch has the following command-line interface:
gch options source_file_name
where
options are the standard gcc options, they should start from -c option
which is mandatory for gcc when calling to compile an Ada source
with GNAT;
source_file_name should be the name of an Ada source file (wild cards are
allowed)
Options from the gch command line do not affect the behavior of gch, but they
are passed as is to gcc when it is called to create a tree file for the ASIS
rule checked and when it is called to create an object file in case if no rule
violation is detected and if creating of the object file is required.
If options contain the '-gnatc' GNAT option, the source is not compiled for
creating the object file.
If you would like to check a source file which depends on some sources located
in directories different from the current directory and from the directory
where the checked source is located, then you have to use -I gcc options just
in the same way as you use them when calling GNAT. The current limitation is,
that when using -I options for a gch call, the current directory is not
searched by default, and you have to use the explicit '-I.' option to tell gch
to look into the current directory when compiling sources.
5. Using gch under Windows 95/NT/98
-----------------------------------
Under Windows 95/NT/98 you can use some bat files that simplify gch usage.
Just put your input Ada files into gch/Tests directory and then run
(double click) the CHECK-ALL.bat to check all *.ad* files in gch/Tests directory
at once getting the output in the RESULT.txt.
You can use CLEAN.bat to clean the Tests directory from files created during
compilation, binding and linking.
6. Adjustment of gch
-----------------
gch does not have command line options on its own, and its operation modes
should be set by means of ini files. Currently there are two ini files to
adjust gch: gch.ini should be used to set general gch options, and
rules.ini should be used to turn on and off checks for particular rules.
When started, gch looks for ini files on the path (the current directory is
not looked in by default). In case if ini file is not found, the default
settings are used.
There is a set of style rules that are checking by the gch. It is possible
to enable/disable each rule of the set without recompilation of the gch.
All rules except Rule_0 and Rule_1 are set enable by default. You can set
a specific rule as you want just putting "+" or "-" to the corresponding line
of the rules.ini file. The corresponding line is located directly before an
exact copy of initialization record of the rule. For example, you can see below
the line for the rule "Ada95 Q&S 4.3.1(10)":
............................................................................
-- + Replacing the plus by minus and back switches the following rule
(Diagnosis => new String' ("explicitly raised predefined exception"),
Rule_Name => new String' ("Q&S 4.3.1(10)"),
On => True,
Global => False,
Rule_To_Check => QS_4_3_1_10'Access),
.............................................................................
Be careful, don't change the layout of the file!
A very simple search method is used now to find out the corresponding lines.
The method would be improved in next versions.
7. Current limitations and future plans
------------------------------------
For the current version, when using '-I' options in gch call, you have to set
the current directory explicitly (by using '-I.'), if you would like sources
from the current directory to be searched in the gcc call that creates the
tree for gch.
The set of rules checked by the current version of gch is rather small, and we
are planning to extend it in the near future.
Another limitation of the current version is that it can process only Ada
sources that exactly follow the GNAT file naming rules (see GNAT Users'
Guide). Source files that don't follow the rules are rejected by the gch version.
We hope to drop this limitation soon.
The important idea of gch is to make it easy for a user who has some
experience in building ASIS applications to add checks for new rules. Of
course, the code for checking a new rule should be provided by the user, but
it should be possible to add this code to the existing code of gch with
minimal and well-located modifications of the existing code. For the current
version, we are not ready to provide the corresponding guidelines, but we are
definitely planning to have this possibility.
8. Related information
-------------------
See GNAT Users' Guide for more information about GNAT options, using gnatmake
and related issues.
See ASIS-for-GNAT Users' Guide for more information about tree files, building
and using ASIS applications with GNAT and related issues.
9. Submitting comments and bug reports
-----------------------------------
Bug reports and comments are very welcome. Send them to Vitali.Sh.Kaufman
(Vitali.Kaufman@iname.com). If you believe, that the problem you have discovered
is a general ASIS problem, send the corresponding report to asis-report@gnat.com.
|
