« back to all changes in this revision
Viewing changes to doc/adacontrol_ug.info
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Ludovic Brenta
- Date: 2006-08-24 08:44:11 UTC
- Revision ID: james.westby@ubuntu.com-20060824084411-1r15uio1h75lqgpx
Tags: upstream-1.4r20
Import upstream version 1.4r20
- files added:
- doc
- rules
- src
- test
- test/conf
- test/ref
added
removed
doc/adacontrol_ug.info
1
This is adacontrol_ug.info, produced by makeinfo version 4.7 from
2
adacontrol_ug.texi.
3
4
5
File: adacontrol_ug.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
6
7
AdaControl User Guide
8
*********************
9
10
This is the AdaControl User Guide. It describes how to install and use
11
AdaControl. Please refer to the AdaControl Programmer Manual to learn
12
how to add new kinds of rules to AdaControl.
13
14
Last edited: 4 October 2005
15
16
* Menu:
17
18
* Introduction::
19
* Installation::
20
* Program Usage::
21
* Rules Usage::
22
* Examples of using AdaControl for common programming rules::
23
24
AdaControl is Copyright (C) 2005 Eurocontrol/Adalog. AdaControl is
25
free software; you can redistribute it and/or modify it under terms of
26
the GNU General Public License as published by the Free Software
27
Foundation; either version 2, or (at your option) any later version.
28
This unit is distributed in the hope that it will be useful, but
29
WITHOUT ANY WARRANTY; without even the implied warranty of
30
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
31
General Public License for more details. You should have received a
32
copy of the GNU General Public License distributed with this program;
33
see file COPYING. If not, write to the Free Software Foundation, 59
34
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
35
36
As a special exception, if other files instantiate generics from this
37
program, or if you link units from this program with other files to
38
produce an executable, this does not by itself cause the resulting
39
executable to be covered by the GNU General Public License. This
40
exception does not however invalidate any other reasons why the
41
executable file might be covered by the GNU Public License.
42
43
This document is Copyright (C) 2005 Eurocontrol/Adalog. This
44
document may be copied, in whole or in part, in any form or by any
45
means, as is or with alterations, provided that (1) alterations are
46
clearly marked as alterations and (2) this copyright notice is included
47
unmodified in any copy.
48
49
50
File: adacontrol_ug.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
51
52
1 Introduction
53
**************
54
55
AdaControl is an Ada rules controller. It is used to control that Ada
56
software meets the requirements of a number of parameterizable rules.
57
It is not intended to supplement checks made by the compiler, but
58
rather to search for particular violations of good-practice rules, or
59
to check that some rules are obeyed project-wide.
60
61
The development of AdaControl was funded by Eurocontrol
62
(`http://www.eurocontrol.int'), which needed a tool to help in
63
verifying the million+ lines of code that does Air Traffic Flow
64
Management over Europe. Because it was felt that such a tool would
65
benefit the community at-large, and that further improvements made by
66
the community would benefit Eurocontrol, it was decided to release
67
AdaControl as free software.
68
69
The requirements for AdaControl were written by Philippe Waroquiers
70
(Eurocontrol-Brussels), who also conducted extensive testing on the
71
Eurocontrol software. The software was developped by Arnaud Lecanu and
72
Jean-Pierre Rosen (Adalog). Some rules were contributed by Richard Toy
73
(Eurocontrol-Maastricht).
74
75
Commercial support is available for AdaControl, see file
76
`doc/support.txt'. If you plan to use AdaControl for industrial
77
projects, or if you want it to be customized or extended to match your
78
own needs, please contact Adalog at info@adalog.fr.
79
80
See file `HISTORY' for a description of the various versions of
81
AdaControl, including enhancements of the current version over the
82
previous ones.
83
84
85
File: adacontrol_ug.info, Node: Installation, Next: Program Usage, Prev: Introduction, Up: Top
86
87
2 Installation
88
**************
89
90
AdaControl is distributed only as source. Like any ASIS application,
91
AdaControl can be run only if the compiler available on the system has
92
exactly the same version as the one used to compile AdaControl itself.
93
Given the current proliferation of various versions of GNAT, it seems
94
better to let the user compile AdaControl himself, thus making sure
95
that there is no mismatch.
96
97
Another reason for distributing AdaControl as source is that the user
98
may not be interested in all provided rules. It is very easy to remove
99
some rules from AdaControl to increase its speed. *Note Customizing
100
AdaControl::.
101
102
* Menu:
103
104
* Prerequisites::
105
* Building AdaControl::
106
* Customizing AdaControl::
107
* Integrating AdaControl into GPS::
108
109
110
File: adacontrol_ug.info, Node: Prerequisites, Next: Building AdaControl, Prev: Installation, Up: Installation
111
112
2.1 Prerequisites
113
=================
114
115
The following software must be installed in order to install AdaControl:
116
* A GNAT compiler, any version. Note that the compiler is also
117
required to use AdaControl (all ASIS application need the
118
compiler).
119
120
* ASIS for GNAT
121
122
Make sure to have the same version of GNAT and ASIS. The version used
123
for running AdaControl must be the same as the one used to compile
124
AdaControl itself.
125
126
It should be possible to compile AdaControl with other compilers than
127
GNAT, although we didn't have an opportunity to try it. If you have
128
another compiler that supports ASIS, note that it may require some easy
129
changes in the package `Implementation_Options' to give proper
130
parameters to the `Associate' procedure of ASIS. Rules that need
131
string pattern matchings need the package `Gnat.Regpat'. If you compile
132
AdaControl with another compiler, you can either port `Gnat.Regpat' to
133
you system, or use a (limited) portable implementation of a simple
134
pattern matching (package `String_Matching_Portable'). Edit the file
135
`string_matching.ads' and change it as indicated in the comments. No
136
other change should be necessary.
137
138
139
File: adacontrol_ug.info, Node: Building AdaControl, Next: Customizing AdaControl, Prev: Prerequisites, Up: Installation
140
141
2.2 Building AdaControl
142
=======================
143
144
The file `Makefile' (in directory `src') should be modified to match
145
the commands and paths of the target system. The following variables
146
are to be set:
147
* EXT
148
149
* SEP
150
151
* RM
152
153
* ASIS_TOP
154
155
* ASIS_INCLUDE
156
157
* ASIS_OBJ
158
159
* ASIS_LIB
160
161
How to set these variables properly is documented in `Makefile'.
162
163
Then, run the make command:
164
$ cd src
165
$ make build
166
167
It is also possible to delete object files and do other actions with
168
this "Makefile", run the following command to get more information:
169
$ make help
170
171
NOTE: Building AdaControl needs the "make" command provide with
172
GNAT; it works both with WIN32 shell and UNIX shell.
173
174
2.3 Testing AdaControl
175
======================
176
177
Testing AdaControl needs a UNIX shell, so it works only with UNIX
178
systems. However, it is possible to run the tests on a WIN32 system by
179
using an UNIX-like shell for WIN32, such as those provided by CYGWIN or
180
MSYS. To run the tests, enter the following commands:
181
$ cd test
182
$ ./run.sh
183
184
All tests must report PASSED. If they don't, here are some hints:
185
* Some UNIX shell emulators add CR's to the end of each line of a
186
text file. Since the reference for the tests is in UNIX (LF only)
187
text format, this may explain the difference. Try running
188
`dos2unix' on the content of the `res/' directory, then do a
189
`diff' on the content of the `res/' and `ref/' directories.
190
191
* If you compiled with GNAT 3.15p, there are known bugs and
192
unimplemented features that will not allow AdaControl to run
193
correctly in some cases. Upgrade to a more recent version of Gnat.
194
195
196
File: adacontrol_ug.info, Node: Customizing AdaControl, Next: Integrating AdaControl into GPS, Prev: Building AdaControl, Up: Installation
197
198
2.4 Customizing AdaControl
199
==========================
200
201
If there are some rules that you are not interested in, it is very easy
202
to remove them from AdaControl:
203
1. In the `src' directory, edit the file `framework-plugs.adb'. There
204
is a `with' clause for each rule (children of package `Rules').
205
Comment out the ones you don't want.
206
207
2. Recompile `framework-plugs.adb'. There will be error messages
208
about unknown procedure calls. Comment out the corresponding lines.
209
210
3. Compile AdaControl normally. That's all!
211
212
It is also possible to add new rules to AdaControl. If your favorite
213
rules are not currently supported, you have several options:
214
1. If you have some funding available, please contact info@adalog.fr.
215
We'll be happy to make an offer to customize AdaControl to your
216
needs.
217
218
2. If you don't have funding, but have some knowledge of ASIS
219
programming, you can add the rule yourself. We have made every
220
effort to make this as simple as possible. Please refer to the
221
AdaControl programmer's manual for details. If you do so, please
222
send your rules to rosen@adalog.fr, and we'll be happy to
223
integrate them in the general release of AdaControl to make them
224
available to everybody.
225
226
3. If you have good ideas, but don't feel like implementing them
227
yourself (nor financing them), please send a note to
228
rosen@adalog.fr. We will eventually incorporate all good
229
suggestions, but we can't of course commit to any dead-line in
230
that case.
231
232
233
File: adacontrol_ug.info, Node: Integrating AdaControl into GPS, Prev: Customizing AdaControl, Up: Installation
234
235
2.5 Integrating AdaControl into GPS
236
===================================
237
238
It is possible to integrate AdaControl into GPS and make it directly
239
available from GPS' menus. Simply copy the file `src/adacontrol.xml'
240
into the `<GPS_dir>/share/gps/customize' directory.
241
242
GPS now features an "AdaControl" entry in the "Tools" menu, which
243
can be used to run AdaControl on the currently edited file. All
244
parameters (including the rule or rule file to use) can be set from the
245
"Project/Edit Project Properties" menu. If you check "AdaControl rules
246
files" in the "Languages" tab, GPS will recognize files with extension
247
`.aru' as AdaControl rules files, and provide appropriate colorization.
248
AdaControl options can be set from the "Switches/AdaControl" tab.
249
250
251
File: adacontrol_ug.info, Node: Program Usage, Next: Rules Usage, Prev: Installation, Up: Top
252
253
3 Program Usage
254
***************
255
256
* Menu:
257
258
* Running AdaControl::
259
* Rules syntax::
260
* Commands::
261
* Command line options and parameters::
262
* Return codes::
263
* Disabling rules::
264
* Helpful utilities::
265
* Optimizing AdaControl::
266
* In case of trouble::
267
268
269
File: adacontrol_ug.info, Node: Running AdaControl, Next: Rules syntax, Prev: Program Usage, Up: Program Usage
270
271
3.1 Running AdaControl
272
======================
273
274
AdaControl is a command-line program, i.e. it's callable directly by a
275
system shell, and can be integrated in GUIs such as GPS (*note
276
Integrating AdaControl into GPS::) or emacs (*note Types and report
277
messages::). It is very simple to use. It takes, as parameters, a list
278
of units to process and a set of rules to apply. AdaControl produces
279
error and/or found messages to the standard output. The type of message
280
(i.e. error or found) depends on the type of the rule (i.e. check or
281
search). It is also possible to locally disable rules for a part of
282
the source code, and various options can be passed to the program.
283
284
Ex:
285
286
Given the following package:
287
package Pack is
288
pragma Pure (Pack);
289
...
290
end Pack;
291
The following command:
292
adactl -l "search pragmas (pure)" pack
293
produces the following result (displayed to standard output):
294
pack.ads:2:4: Found: PRAGMAS: use of pragma Pure
295
296
297
File: adacontrol_ug.info, Node: Rules syntax, Next: Commands, Prev: Running AdaControl, Up: Program Usage
298
299
3.2 Rules syntax
300
================
301
302
AdaControl is about checking rules. Each rule has a name, and may
303
require parameters. Which rules are to be checked is specified either
304
on the command line or in a rules file; in either case, the syntax for
305
specifying rules is as follows:
306
[<label> ":"] "check"|"search"|"count" <Name>
307
["(" [<modifiers>] <parameter> {"," [<modifiers>] <parameter>}")"] ";"
308
309
If present, the label gives a name to the rule; it will be printed
310
whenever the rule is activated, and can be used to disable the rule.
311
*Note Disabling rules::. If no label is present, the rule name is
312
printed instead. Note that there is no problem in specifying the same
313
label for several rules.
314
315
Each rule consists of a rule type followed by a rule name, and
316
(optionally) parameters. Some parameters may be preceded by modifiers
317
(such as "not" or "case_sensitive"). The meaning of the rule parameters
318
and modifiers depends on the rule. The case of the rule type, rule
319
name, and parameters is not significant. A syntax error in a rule
320
causes the execution to stop.
321
322
Since wide characters are allowed in Ada programs, AdaControl accepts
323
wide characters in rules as well. With GNAT, the encoding scheme is Hex
324
ESC encoding (see the GNAT User-Guide/Reference-Manual). This is the
325
prefered method, since few people require wide characters in programs
326
anyway, and that keeping the defaul bracket encoding would not
327
conveniently allow brackets for regular expressions, like those
328
required for the rule "Naming_Convention" (*note Naming_Convention::).
329
330
* Menu:
331
332
* Types and report messages::
333
* Parameters::
334
* Specifying an Ada entity name::
335
* Multiple rules::
336
337
338
File: adacontrol_ug.info, Node: Types and report messages, Next: Parameters, Prev: Rules syntax, Up: Rules syntax
339
340
3.2.1 Types and report messages
341
-------------------------------
342
343
There are three rule types:
344
345
* check
346
347
* search
348
349
* count
350
351
"Check" is intended to search for rules that must be obeyed in your
352
programs. Normally, if a "Check" rule fails, you should fix the
353
program. "Search" is intended to report some situations, but you should
354
consider what to do on a case-by-case basis. Roughly, use "check" when
355
you consider that the failure of the rule is an error, and "search"
356
when you consider it as a warning. AdaControl will exit with a status
357
of 1 if any "Check" rule is triggered, and a status of 0 if only
358
"Search" rule were triggered (or no rule was triggered at all).
359
360
"Count" works like "search", but instead of printing a message for
361
each rule which is triggered, it simply counts occurrences and prints a
362
summary at the end of the run. There is a separate count for each rule
363
label (or if no label is given, the rule name is taken instead); if you
364
give the same label to different rules, this allows you to accumulate
365
the counts.
366
367
A report message (except for the final report of "count") is made of
368
(separated by ':'):
369
370
* the file name (where the rule matches)
371
372
* the line number (where the rule matches)
373
374
* the column number (where the rule matches)
375
376
* the rule id (the rule that matches) or the rule label if there is
377
one.
378
379
* a message (why the rule matches)
380
381
A rule whose type is "check" will produce an error report message
382
(i.e. containing the keyword ERROR) and a rule use whose type is
383
"search" will produce a found report message (i.e. containing the
384
keyword FOUND).
385
386
Note that the format used for report messages is the same as the one
387
used by GNAT error messages. Editors (like Emacs or GPS) that recognize
388
this format allow you to go directly to the place of the message by
389
clicking on it.
390
391
392
File: adacontrol_ug.info, Node: Parameters, Next: Specifying an Ada entity name, Prev: Types and report messages, Up: Rules syntax
393
394
3.2.2 Parameters
395
----------------
396
397
Some rules work with parameters. Parameters can be:
398
* an Ada entity name
399
400
* an Ada keyword
401
402
* a keyword for the rule
403
404
* a numerical value
405
406
A numerical value is given with the syntax of an Ada integer litteral
407
(underscores are allowed as in Ada). Based litterals are not currently
408
supported; if somebody can justify a need for them, we'll be happy to
409
add this feature later...
410
411
An Ada entity name can be followed by overloading information (see
412
below), in order to uniquely identify the Ada entity. If an Ada entity
413
is overloaded and no overloading information is provided, the rule is
414
applied to all (overloaded) Ada entities that match the name.
415
416
417
File: adacontrol_ug.info, Node: Specifying an Ada entity name, Next: Multiple rules, Prev: Parameters, Up: Rules syntax
418
419
3.2.3 Specifying an Ada entity name
420
-----------------------------------
421
422
The syntax of the <Ada_Entity_Name> is as follows:
423
<Ada_Entity_Name> ::= <Full_Name> | "all" <Simple_Name> | "all" <Attribute>
424
`<Full_Name>' is the full name of the Ada entity, using normal Ada
425
dot notation (with some extensions, see below)). Full name means that
426
you give the full expanded name, starting from a compilation unit. This
427
name must be the actual full name, i.e. it must not include any
428
renaming (otherwise the name will not be recognized). For example, the
429
usual `Put_Line' must be given as `Ada.Text_IO.Put_Line', not as
430
`Text_IO.Put_Line'. Predefined elements (`Integer', `Constraint_Error')
431
must be given in the form `Standard.Integer' or
432
`Standard.Constraint_Error', since they are logically declared in the
433
package `Standard'.
434
435
`<Simple_Name>' is a single identifier, possibly followed by
436
overloading information. No qualification is allowed.
437
438
`<Attribute>' is an attribute name, including the quote. No
439
overloading information is allowed.
440
441
`<Full_Name>' designates a single entity or several overloaded
442
entities declared in the same place (as identified by the prefix),
443
while `all <simple_name>' designates all identifiers with the given
444
name in the program, irrespectively of where they appear. `all
445
<Attribute>' designates all occurrences of the given attribute,
446
irrespectively of what the attribute applies to.
447
448
A utility is provided with AdaControl to help you find the full name
449
of an entity. *Note pfni::.
450
451
3.2.3.1 Overloaded names
452
........................
453
454
In Ada, names can be overloaded. This means that you can have several
455
procedures `P' in package ` Pack', if they differ by the types of the
456
parameters. If you just give the name `Pack.P' as the
457
<Ada_Entity_Name>, the corresponding rule will be applied to all
458
elements named `P' from package `Pack'. If you want to distinguish
459
between overloaded names, you can specify a profile after the element's
460
name. A profile has the syntax:
461
462
"{" [ ["access"] <type-name>
463
{ ";" ["access"] <type-name> } ]
464
["return" <type-name>] "}"
465
466
You must specify the type name, even if the <Ada_Entity_Name>
467
declaration uses a subtype of the type; this is because Ada uses types
468
for overloading resolution, not subtypes. Anonymous access parameters
469
are specified by putting `access' in front of the type name. An
470
overloaded name for a procedure without parameters uses just a pair of
471
empty brackets. If the subprogram is a function, you must provide the
472
`return <type-name>' part for the return type of the function. The
473
types must also be given as a unique name, i.e. including the full
474
path: if the type is `T' declared in package `Pack', you must specify
475
it as `Pack.T'. As a convenience, the `Standard.' is optional for
476
predefined types, so you can write `Standard.Integer' as `Integer'.
477
There is no ambiguity, since a type is always declared within some
478
construct. Note that omitting `Standard' works only for types that are
479
part of the profile used to distinguish between overloaded Ada entities
480
but that the Ada entity name must always contain Standard if it is a
481
predefined element.
482
483
Overloaded names can be also be used with the `all <Simple_Name>'
484
form of the <Ada_Entity_Name>. In this case, the rule will be applied to
485
all names that are subprograms with the given identifier and matching
486
the given profile, irrespectively of where they appear.
487
488
Note that if you use an overloaded name, all overloadable names that
489
are part of the <Ada_Entity_Name>, including those of the profile, must
490
use the overloaded syntax. For example, given the following program
491
procedure P is
492
procedure Q (I : Integer) is
493
...
494
end Q;
495
procedure Q (F : Float) is
496
...
497
end Q;
498
begin
499
...
500
end P;
501
502
If you want to distinguish between the two procedures `Q', you must
503
specify them as `P{}.Q{Integer}' and `P{}.Q{Float}' (note the `P{}'
504
which specifies an overloaded name for a procedure `P' without
505
parameters).
506
507
The names of entities which can not be overloaded (like package,
508
exception, ...) must not be suffixed by braces (e.g.
509
`Ada.Text_IO.Put_Line{Standard.String}').
510
511
3.2.3.2 Enumeration literals
512
............................
513
514
Following normal Ada rules, an enumeration literal is considered a
515
parameterless function. If you want to distinguish between overloaded
516
enumeration literals, you can use overloaded names for them. For
517
example, given:
518
package Pack is
519
type T1 is (A, B);
520
type T2 is (B, C);
521
end Pack;
522
523
Ada entities names are:
524
* `Pack.B{return Pack.T1}'
525
526
* `Pack.B{return Pack.T2}'
527
528
3.2.3.3 Operators
529
.................
530
531
AdaControl handles operators (i.e. functions like `"+"') correctly. Of
532
course, you must specify such operations using normal Ada syntax: if
533
you define the integer type `T' in package `Pack', an overloaded name
534
for the addition would be `Pack."+"{Pack.T; Pack.T return Pack.T}'.
535
536
3.2.3.4 Attributes
537
..................
538
539
It is also possible to designate attributes, using the normal notation
540
(i.e. `Standard.Integer'First'). If the name of an attribute which is a
541
function appears in a name that uses the overloaded syntax, it is not
542
necessary (and actually not allowed) to provide its profile, since
543
there is no possible ambiguity in that case. For example, given:
544
545
procedure P (I : Integer) is
546
type T is range 1 .. 10;
547
begin
548
...
549
end P;
550
551
You can designate the `'Image' attribute for type `T' as
552
`P{Standard.Integer}.T'Image' (the profile of the `'Image' function is
553
not given, as would be necessary for a normal function).
554
555
3.2.3.5 Anonymous constructs
556
............................
557
558
There is a special case for elements that are defined (directly or
559
indirectly) within unnamed loops or block statements. Everything
560
happens as if the unnamed construct was named `_anonymous_'. So if you
561
have the following program:
562
procedure P is
563
begin
564
for I in 1..10 loop
565
declare
566
J : Integer;
567
begin
568
...
569
end;
570
end loop;
571
end P;
572
You can refer to `I' as `P._anonymous_.I', and to `J' as
573
`P._anonymous_._anonymous_.J'.
574
575
3.2.3.6 Record and protected types components
576
.............................................
577
578
You can designate the name of a record or protected type component (a
579
"field" name), but to identify it uniquely, you must precede its name
580
by the name of the type. This is a small extension to Ada syntax, but
581
it is the simplest and most natural way to deal with this case. For
582
example, given:
583
procedure P is
584
type T is
585
record
586
Name : Integer;
587
end record;
588
...
589
590
The Ada entity name is `P.T.Name'.
591
592
3.2.3.7 Formals of access to subprogram types
593
.............................................
594
595
Similarly, you can designate the formal of an access to subprogram type
596
by prefixing it by the access type. For example, given:
597
procedure P is
598
type T is access procedure (X : Integer);
599
...
600
601
The Ada entity name of the formal is `P.T.X'.
602
603
604
File: adacontrol_ug.info, Node: Multiple rules, Prev: Specifying an Ada entity name, Up: Rules syntax
605
606
3.2.4 Multiple rules
607
--------------------
608
609
Most rules can be given more than once (with different parameters).
610
There is no difference between a single or a multiple configuration
611
rule use: ouputs, efficiency, etc. are the same.
612
613
The following configuration files produce an identical configuration:
614
Search Pragmas (Pure, Elaborate_All);
615
and
616
Search Pragmas (Pure);
617
Search Pragmas (Elaborate_All);
618
619
However, the second form can be used to give different labels.
620
Consider:
621
Search Pragmas (Pure);
622
No_Elaborate: Search Pragmas (Elaborate_All);
623
624
The messages for pragma `Pure' will contain "PRAGMAS", while those
625
for `Elaborate_All' will contain "No_Elaborate". If a disabling comment
626
mentions `pragmas', it will disable both rules, but a disabling comment
627
that mentions `No_Elaborate' will disable only the second one.
628
629
630
File: adacontrol_ug.info, Node: Commands, Next: Command line options and parameters, Prev: Rules syntax, Up: Program Usage
631
632
3.3 Commands
633
============
634
635
In addition to rules specification, AdaControl recognizes a number of
636
commands. Although these commands are especially useful when using the
637
interactive mode (*note Interactive mode::), they can be used in
638
command files as well.
639
640
* Menu:
641
642
* Go command::
643
* Quit command::
644
* Message command::
645
* Help command::
646
* Clear command::
647
* Set command::
648
* Source command::
649
* Inhibit command::
650
* Example of commands::
651
652
653
File: adacontrol_ug.info, Node: Go command, Next: Quit command, Prev: Commands, Up: Commands
654
655
3.3.1 Go command
656
----------------
657
658
Syntax:
659
go;
660
This command starts processing of the rules that have been
661
specified. Rules are not reset after a "go" command; for example, the
662
following program:
663
search entities (pack1);
664
go;
665
search entities (pack2);
666
go;
667
will first output all usages of `Pack1', then all usages of both
668
`Pack1' and `Pack2'. See *Note Clear command:: to reset rules.
669
670
If not in interactive mode, a "go" command is automatically added,
671
therefore it is not required in rules files.
672
673
674
File: adacontrol_ug.info, Node: Quit command, Next: Message command, Prev: Go command, Up: Commands
675
676
3.3.2 Quit command
677
------------------
678
679
Syntax:
680
quit;
681
This command terminates AdaControl. If given in a file, all
682
subsequent commands will be ignored. This command is really useful only
683
in interactive mode. *Note Interactive mode::.
684
685
686
File: adacontrol_ug.info, Node: Message command, Next: Help command, Prev: Quit command, Up: Commands
687
688
3.3.3 Message command
689
---------------------
690
691
Syntax:
692
message <any string>;
693
This command prints the given message on the output file. The length
694
of the message is limited to 250 characters.
695
696
Note that the message is terminated by the first ";" encountered. If
697
a message needs to include a ";", the hole message must be quoted
698
(double quotes).
699
700
701
File: adacontrol_ug.info, Node: Help command, Next: Clear command, Prev: Message command, Up: Commands
702
703
3.3.4 Help command
704
------------------
705
706
Syntax:
707
Help [ all | <rule name>{,<rule name>} ];
708
Without any argument, this command prints a summary of all commands
709
and rule names. If given one or more rule names, it prints the detailed
710
help for the given rules. If given the keyword `all', it prints the
711
detailed help for all rules.
712
713
714
File: adacontrol_ug.info, Node: Clear command, Next: Set command, Prev: Help command, Up: Commands
715
716
3.3.5 Clear command
717
-------------------
718
719
Syntax:
720
Clear all | <rule name>{,<rule name>} ;
721
This command clears all "count", "search", and "check" commands
722
given for the indicated rules, of for all rules if the `all' keyword is
723
given. For example, the following program:
724
search entities (pack1);
725
go;
726
clear all;
727
search entities (pack2);
728
go;
729
will first output all usages of `Pack1', then all usages of `Pack2'.
730
Without the "clear all" command, the second "go" would output all
731
usages of `Pack1' together with all usages of `Pack2'.
732
733
734
File: adacontrol_ug.info, Node: Set command, Next: Source command, Prev: Clear command, Up: Commands
735
736
3.3.6 Set command
737
-----------------
738
739
Syntax:
740
set Output <output file>;
741
set Verbose | Debug | Ignore On | Off
742
In the first form, this command redirects the output of subsequent
743
checks to the indicated file. If the string `console' (case irrelevant)
744
is given as the <output file>, output is redirected to the console.
745
746
As with the "-o" option, if the file exists, output is appended to
747
it, unless the "-w" option is given, in which case it is overwritten.
748
However, the file is overwritten only the first time it is mentionned
749
in an "output" command. This means that you can switch forth and back
750
between two output files, all results from the same run will be kept.
751
Note however that for this to work, you need to specify the output file
752
exactly the same way: if you specify it once as "result.txt", and then
753
as "./result.txt", the second one will overwrite the first one.
754
755
In the second form, this command allows to activate ("on") or
756
deactivate ("off") options. "Verbose" corresponds to the "-v" option,
757
"Debug" to the "-d" option, and "Ignore" to the "-i" option. See *Note
758
Verbose and debug mode:: and *Note Local deactivation ignoring:: for
759
details.
760
761
762
File: adacontrol_ug.info, Node: Source command, Next: Inhibit command, Prev: Set command, Up: Commands
763
764
3.3.7 Source command
765
--------------------
766
767
Syntax:
768
Source <input file>;
769
This command redirects the input of commands from the indicated
770
file. Commands and rules are read and executed from the indicated file,
771
then control is returned to the place after the "source" command. There
772
is no restriction on the content of the sourced file; especially, it
773
may itself include other "source" commands.
774
775
If the string `console' (case irrelevant) is given as the <input
776
file>, commands are read from the console until a "quit" command is
777
given. This command is of course useful only from files, and allows to
778
pass temporarily control to the user in interactive mode.
779
780
781
File: adacontrol_ug.info, Node: Inhibit command, Next: Example of commands, Prev: Source command, Up: Commands
782
783
3.3.8 Inhibit command
784
---------------------
785
786
Syntax:
787
Inhibit <rule name> (<unit> {,<unit>});
788
This command will inhibit execution of the rule for the indicated
789
unit(s). There are several reasons why you might want to inhibit a rule
790
for certain units:
791
* The unit is known not to obey the rule in many places, and you
792
don't want the output to be cluttered with too many messages (of
793
course, you'll fix the unit in the near future!);
794
795
* The unit is known to obey the rule, and you want to save some
796
processing time;
797
798
* The unit is known to raise an ASIS bug, and until you upgrade to
799
the appropriate version of GNAT, you don't want to be bothered by
800
the error messages.
801
802
803
File: adacontrol_ug.info, Node: Example of commands, Prev: Inhibit command, Up: Commands
804
805
3.3.9 Example of commands
806
-------------------------
807
808
Below is an example of a file with multiple commands:
809
message "Searching Unchecked_Conversion";
810
search entitities (ada.unchecked_conversion);
811
output uc_usage.txt;
812
go;
813
clear all;
814
message "Searching 'Address";
815
search attribute (address);
816
output address_usage.txt;
817
go;
818
This file will output all usages of `Ada.Unchecked_Conversion' into
819
the file `uc_usage.txt', then output all usages of the `'Address'
820
attribute into the file `address_usage.txt'. Messages are output to
821
tell the user about what's happenning.
822
823
824
File: adacontrol_ug.info, Node: Command line options and parameters, Next: Return codes, Prev: Commands, Up: Program Usage
825
826
3.4 Command line options and parameters
827
=======================================
828
829
Options are introduced by a "-" followed by a letter and can be grouped
830
as usual. Some options take the following word on the command line as a
831
value; such options must appear last in a group of options. Parameters
832
are words on the command line that stand by themselves. Options and
833
parameters can be given in any order.
834
835
The complete syntax for invoking AdaControl is:
836
837
adactl [-deiIrsuvw] [-f <rules file>] [-l <rules list>] [-o <output file>]
838
[-p <project file>] {<unit>[+|-<unit>]|[@]<file>} [-- <ASIS options>]
839
or
840
adactl -h [<rule id>... | all]
841
or
842
adactl -D [-rsw] [-o <output file>] [-p <project file>]
843
{<unit>[+|-<unit>]|[@]<file>} [-- <ASIS options>]
844
Using AdaControl with the "-D" option is described later. *Note
845
Helpful utilities::.
846
847
* Menu:
848
849
* Getting help::
850
* Input units::
851
* Specifying rules::
852
* Output file::
853
* Interactive mode::
854
* Local deactivation ignoring::
855
* Verbose and debug mode::
856
* Treat warnings as errors::
857
* Exit on error::
858
* Project files::
859
* ASIS options::
860
861
862
File: adacontrol_ug.info, Node: Getting help, Next: Input units, Prev: Command line options and parameters, Up: Command line options and parameters
863
864
3.4.1 Getting help
865
------------------
866
867
The "-h" option alone displays a help message about usage of the
868
AdaControl program, the various options, and the rule names. If the
869
"-h" is followed by one or several rule names (case irrelevant), it
870
displays the help message for the rule(s). If the "-h" option is
871
followed by the keyword "all", it displays the help message for all
872
rules.
873
874
Ex:
875
adactl -h
876
adactl -h pragmas Unnecessary_Use_Clause
877
adactl -h all
878
Note that if the "-h" option is given, no other option is analyzed
879
and no further processing happens.
880
881
882
File: adacontrol_ug.info, Node: Input units, Next: Specifying rules, Prev: Getting help, Up: Command line options and parameters
883
884
3.4.2 Input units
885
-----------------
886
887
Units to be processed are simply given as parameters on the command
888
line. Note that they are Ada compilation unit names, not file names:
889
case is not significant, and there should be no extension! Of course,
890
child units are allowed following normal Ada naming rules:
891
`Parent.Child'. Note that when a unit is processed, all its subunits
892
are processed at the same time; therefore, there is no need to specify
893
subunits.
894
895
However, as a convenience to the user, units can be specified as file
896
names, provided they follow the default GNAT naming convention. More
897
precisely, if a parameter ends in ".ads" or ".adb", the unit name is
898
extracted from it (and all "-" in the name are substituted with ".").
899
File names can include a path; in this case, the path is automatically
900
added to the list of directories searched ("-I" option). The file
901
notation is convenient to process all units in a directory, as in the
902
following example:
903
adactl -f my_rules.aru *.adb
904
905
In the unlikely case where you have a child unit called `Ads' or
906
`Adb', use the "-u" option to force interpretation of all parameters as
907
unit names.
908
909
By default, both the specification and body of the unit are
910
processed; however, it is possible to specify processing of the
911
specification only by providing the "-s" option. If only file names are
912
given, the "-s" option is assumed if all files are specifications
913
(".ads" files). It is not possible to specify processing of bodies
914
only, since rules dealing with visibility would not work.
915
916
The "-r" option tells AdaControl to process (recursively) all user
917
units that the specified units depend on (including parent units if the
918
unit is a child unit or a subunit). Predefined Ada units and units
919
belonging to the compiler's run-time library are never processed.
920
921
Ex:
922
adactl -r -f my_rules.aru my_main
923
will process `my_main' and all units that `my_main' depends on. If
924
`my_main' is the main procedure, this means that the whole program will
925
be processed.
926
927
It is possible to specify more than one unit (not file) to process in
928
a parameter by separating the names with "+". Conversely, it is
929
possible to specify units that are not to be processed, separated by
930
"-". When a unit is subtracted from the unit list, it is never
931
processed even if it is included via the recursive option, and all its
932
child and separate units are also excluded. This is convenient to avoid
933
processing reusable components, that are not part of a project. For
934
example, if you want to run AdaControl on itself, you should use the
935
following command:
936
adactl -f my_rules_file.aru -r adactl-asis-a4g
937
This applies the rules from the file `my_rules_files.aru' to
938
AdaControl itself, but not to units that are part of ASIS (the "-r"
939
(recursive) option would find them otherwise).
940
941
Alternatively, it is possible to give a parameter as an "@" followed
942
by the name of a file. This file must contain a list of unit names (not
943
files), one on each line. All units whose names are given in the file
944
will be processed. If a name in the file starts with "@", it will also
945
be treated as an indirect file (i.e. the same process will be invoked
946
recursively). If a line in the file starts with a "#" character, it is
947
ignored. This can be useful to temporarily disable the processing of
948
some files or to add comments.
949
950
Ex:
951
adactl -f my_rules.aru @unit_file.txt
952
953
954
File: adacontrol_ug.info, Node: Specifying rules, Next: Output file, Prev: Input units, Up: Command line options and parameters
955
956
3.4.3 Specifying rules
957
----------------------
958
959
Rules list can be passed on the command line using the "-l" option.
960
Rules list must be quoted with """.
961
962
Ex:
963
adactl pack.ads proc.adb -l "check instantiations (My_Generic);"
964
It is possible to pass several rules separated by ";" as usual, but
965
as a convenience to the user, the last ";" may be omitted.
966
967
Rules list can also be passed from a file, whose name must be given
968
after the "-f" option. As a special case, if the file name is "-",
969
rules are read from the standard input. This is intended to allow
970
AdaControl to be pipelined behind something that generates commands; if
971
you want to type rules directly to AdaControl, the interactive mode is
972
more appropriate. *Note Interactive mode::.
973
974
Ex:
975
adactl -f my_rules.aru proc.adb
976
977
A rule file must contain at least one rule. The layout of rules is
978
free (i.e. a rule can extend over several lines, and spaces are allowed
979
between syntactic elements). A rule file may also contain comment
980
lines. Comments begin with a "#" or a "--", and extend to the end of
981
the line. Comments can be placed anywhere in the file.
982
983
Ex:
984
# My rules file
985
# generated by myself 2004.09.27.14.12.36
986
search rule1 (param1, param2, param3); -- This is Rule 1
987
My_Label: check rule2 (param1);
988
search rule3 (param1,
989
-- Comment in the middle
990
param2,
991
param3, param4);
992
search rule4; -- A rule without parameters
993
994
Note that the "-l" and "-f" options are not exclusive: if both are
995
specified, the rules to be checked include those in the file and those
996
given on the command line.
997
998
999
File: adacontrol_ug.info, Node: Output file, Next: Interactive mode, Prev: Specifying rules, Up: Command line options and parameters
1000
1001
3.4.4 Output file
1002
-----------------
1003
1004
By default, the standard output is used for output. The default output
1005
can be changed by specifying an output file with the "-o" option.
1006
1007
Ex:
1008
adactl -f my_rules.aru -o my_output.txt proc.adb
1009
Error and found rule messages are output to the output file. Syntax
1010
error messages for rules and possible internal errors from AdaControl
1011
itself are output to the standard error file.
1012
1013
If the output file exists, new messages are appended to it. This
1014
allows running AdaControl under several directories that make up the
1015
project, and gathering the results in a single file. However, if the
1016
"-w" option is given, AdaContol overwrites the output file if it exists.
1017
1018
Ex:
1019
adactl -w -f my_rules.aru -o my_output.txt proc.adb
1020
1021
1022
File: adacontrol_ug.info, Node: Interactive mode, Next: Local deactivation ignoring, Prev: Output file, Up: Command line options and parameters
1023
1024
3.4.5 Interactive mode
1025
----------------------
1026
1027
The "-I" option tells AdaControl to operate interactively. In this
1028
mode, commands and rules specified with "-l" or "-f" options are first
1029
processed, then AdaControl prompts for commands on the terminal. Note
1030
that the "quit" command (*note Quit command::) is used to terminate
1031
AdaControl.
1032
1033
The syntax for rules and commands is exactly the same as the one used
1034
for files; especially, each rule or command must be terminated with a
1035
";". Note that the prompt ("Command:") becomes ".......:" when
1036
AdaControl requires more input because a command is not completely
1037
given, and especially if you forget the final ";".
1038
1039
The interactive mode is useful when you want to do some analysis of
1040
your code, but don't know beforehand what you want to check. Since the
1041
ASIS context is open only once when the program is loaded, queries will
1042
be much faster than running AdaControl entirely with a new query given
1043
in a "-l" option each time. It is also useful to experiment with
1044
AdaControl, and to check interactively commands before putting them
1045
into a file.
1046
1047
1048
File: adacontrol_ug.info, Node: Local deactivation ignoring, Next: Verbose and debug mode, Prev: Interactive mode, Up: Command line options and parameters
1049
1050
3.4.6 Local deactivation ignoring
1051
---------------------------------
1052
1053
The "-i" option tells AdaControl to ignore deactivation tags in Ada
1054
source code (*note Disabling rules::).
1055
1056
Ex:
1057
adactl -i -f my_rules.aru proc.adb
1058
1059
1060
File: adacontrol_ug.info, Node: Verbose and debug mode, Next: Treat warnings as errors, Prev: Local deactivation ignoring, Up: Command line options and parameters
1061
1062
3.4.7 Verbose and debug mode
1063
----------------------------
1064
1065
In the default mode, AdaControl displays only rule messages. It is
1066
possible to get more information with the verbose option ("-v"). In
1067
this mode, AdaControl displays unit names as they are processed, and
1068
prints its global execution time when it finishes.
1069
1070
Ex:
1071
adactl -v -f my_rules.aru proc.adb
1072
It is also possible to get more information in case of a program
1073
error by using the debug mode. Debug mode is enabled by using the "-d"
1074
option.
1075
1076
Ex:
1077
adactl -d -f my_rules.aru proc.adb
1078
1079
1080
File: adacontrol_ug.info, Node: Treat warnings as errors, Next: Exit on error, Prev: Verbose and debug mode, Up: Command line options and parameters
1081
1082
3.4.8 Treat warnings as errors
1083
------------------------------
1084
1085
The "-e" option tells AdaControl to treat warnings as errors, i.e. to
1086
report a return code of 1 even if only "search" rules were triggered.
1087
*Note Return codes::. It does not change the messages however.
1088
1089
1090
File: adacontrol_ug.info, Node: Exit on error, Next: Project files, Prev: Treat warnings as errors, Up: Command line options and parameters
1091
1092
3.4.9 Exit on error
1093
-------------------
1094
1095
If an error is encountered during processing a unit, AdaControl will
1096
continue to process other units. However, if the "-x" option is given,
1097
AdaControl will stop on the first error encountered. This option is
1098
mainly useful if you want to debug AdaControl itself (or your own
1099
rules). *Note In case of trouble::.
1100
1101
Ex:
1102
adactl -x -f my_rules.aru proc.adb
1103
1104
1105
File: adacontrol_ug.info, Node: Project files, Next: ASIS options, Prev: Exit on error, Up: Command line options and parameters
1106
1107
3.4.10 Project files
1108
--------------------
1109
1110
3.4.10.1 Emacs style project files
1111
..................................
1112
1113
An emacs project file (the file with a ".adp" extension used by the Ada
1114
mode of Emacs) can be specified with the " -p" option. AdaControl will
1115
automatically consider all the directories mentioned in "src_dir" lines
1116
from the project file.
1117
1118
Ex:
1119
adactl -f my_rules.aru -p proj.adp proc.adb
1120
1121
3.4.10.2 GPS project files
1122
..........................
1123
1124
Currently, ASIS does not accept the "-P" option for GPS style project
1125
files. Should this change in the future, a "-P" option could be passed
1126
as described for the "-I" option. *Note ASIS options::.
1127
1128
In the meantime, it is possible to use GPS project files by first
1129
compiling the modules to be checked with the "-gnatct" option (and of
1130
course the "-P" option for the project); this will save the so-called
1131
"tree files", which will appear with an ".adt" extension. AdaControl
1132
will use the tree files if they are available (and up to date), thus
1133
saving the recompilation and the need to specify any "-I" or "-P"
1134
option.
1135
1136
After running the tool, the tree files can be deleted.
1137
1138
1139
File: adacontrol_ug.info, Node: ASIS options, Prev: Project files, Up: Command line options and parameters
1140
1141
3.4.11 ASIS options
1142
-------------------
1143
1144
Everything that appears on the command line after "--" will be treated
1145
as an ASIS option, as described in the ASIS user manual.
1146
1147
Casual users don't need to care about ASIS options, except in one
1148
case: if the units that you are processing reference other units whose
1149
source is not in the same directory, AdaControl needs to know how to
1150
access these units (as GNAT would). This can be done either using an
1151
Emacs project file (the "-p" option), or by passing a "-I" option to
1152
ASIS, or by using ADA_INCLUDE_PATH.
1153
1154
It is possible to include one or several "-I" options to reference
1155
other directories where sources can be found. The syntax is the same as
1156
the "-I" option for GNAT.
1157
1158
Other ASIS options, like the "-Cx" and/or "-Fx" options, can be
1159
specified. Most users can ignore this feature; however, specifying
1160
these options can improve the processing time of big projects. *Note
1161
Optimizing AdaControl::.
1162
1163
1164
File: adacontrol_ug.info, Node: Return codes, Next: Disabling rules, Prev: Command line options and parameters, Up: Program Usage
1165
1166
3.5 Return codes
1167
================
1168
1169
In order to ease the automation of rules checking with shell scripts,
1170
AdaControl returns various error codes depending on how successful it
1171
was. Values returned are:
1172
* 0: At most "search" rules were triggered (no rule at all with "-e"
1173
option)
1174
1175
* 1: At least one "check" rule was triggered (or at least one
1176
"search" or "check" rule with "-e" option)
1177
1178
* 2: AdaControl was not run due to a syntax error in the rules or in
1179
the specification of units.
1180
1181
* 10: There was an internal failure of AdaControl.
1182
1183
1184
File: adacontrol_ug.info, Node: Disabling rules, Next: Helpful utilities, Prev: Return codes, Up: Program Usage
1185
1186
3.6 Disabling rules
1187
===================
1188
1189
It is possible to disable rules on parts of the source code by placing
1190
a tag (special Ada comment) in the source code. This can be done in two
1191
ways: block disabling or line disabling. The disabling tag is "--##".
1192
Both ways take a list of rules to disable as parameters. A list of
1193
rules is a list of rule names or rule labels, separated by spaces.
1194
Alternatively, the list of rules can be the word "all" to disable all
1195
rules.
1196
1197
In a "-##" line, everything appearing after a second occurrence of
1198
"##" is ignored. This allows the insertion of a comment explaining why
1199
the rule is disabled at that point.
1200
1201
3.6.1 Block disabling
1202
---------------------
1203
1204
A rule is disabled from the "rule off" tag until the "rule on" tag. If
1205
there is no "rule on" tag, the rule is disabled up to the end of file.
1206
1207
Syntax:
1208
--## rule off <rule_list>
1209
Ada code block
1210
--## rule on <rule_list>
1211
1212
Ex:
1213
--## rule off rule1 rule2
1214
I := I + 1;
1215
Proc (I);
1216
--## rule on rule2
1217
1218
3.6.2 Line disabling
1219
--------------------
1220
1221
The rule is disabled only for the line where the tag appears.
1222
1223
Syntax:
1224
Ada code line --## rule line off <rule_list>
1225
Ex:
1226
I := I + 1; --## rule line off rule3 rule_label_1
1227
Conversely, it is possible to re-enable a rule for just the current
1228
line in a block where rules are disabled:
1229
1230
Syntax:
1231
Ada code line --## rule line on <rule_list>
1232
Ex:
1233
I := I + 1; --## rule line on rule3
1234
1235
1236
File: adacontrol_ug.info, Node: Helpful utilities, Next: Optimizing AdaControl, Prev: Disabling rules, Up: Program Usage
1237
1238
3.7 Helpful utilities
1239
=====================
1240
1241
This section describe utilities that are handy to use in conjunction
1242
with AdaControl.
1243
1244
* Menu:
1245
1246
* pfni::
1247
* Adactl -D::
1248
1249
1250
File: adacontrol_ug.info, Node: pfni, Next: Adactl -D, Prev: Helpful utilities, Up: Helpful utilities
1251
1252
3.7.1 pfni
1253
----------
1254
1255
The convention used to refer to entities (as described in *Note
1256
Specifying an Ada entity name::) is very powerful, but it may be
1257
difficult to spell out correctly the name of some entities, especially
1258
when using the overloaded syntax.
1259
1260
`pfni' (which stands for Print Full Name Image) can be used to get
1261
the correct spelling for any Ada entity. The syntax of `pfni' is:
1262
pfni [-sofd] [-p <project-file>] <unit>[:<line_number>[:<column_number>]]
1263
[-- <ASIS options>]
1264
or
1265
pfni -h
1266
If called with the "-h" option, `pfni' prints a help message and
1267
exits.
1268
1269
Otherwise, `pfni' prints the full name image of all identifiers
1270
declared in the given unit, unless there is a "-f" (full) option, in
1271
which case it prints the full name image of all identifiers (i.e.
1272
including those that are used, but not declared, in the unit). If a
1273
<line_number> is given, only identifiers on that line are printed. If
1274
both <line_number> and <column_number> are given, only the identifier
1275
(if any) at the given line and column is printed. The image is printed
1276
without overloading information, unless the "-o" option is given.
1277
1278
If the "-s" option is given, the specification of the unit is
1279
processed, otherwise the body is processed. The "-p" option specifies
1280
the name of an Emacs project file, and the "-d" option is the debug
1281
mode, as for AdaControl itself. ASIS options can be passed like for
1282
AdaControl.
1283
1284
As a side usage of `pfni', if you are calling a subprogram that has
1285
several overloadings and you are not sure which one is called, use
1286
`pfni' with the "-o" option on that line: the program will tell you the
1287
full name and profile of the called subprogram.
1288
1289
1290
File: adacontrol_ug.info, Node: Adactl -D, Prev: pfni, Up: Helpful utilities
1291
1292
3.7.2 Adactl -D
1293
---------------
1294
1295
When run with the "-D" option, AdaControl simply outputs the list of
1296
units that would be processed.
1297
1298
This list can be directed to a file with the "-o" option (if the
1299
file exists, it won't be overwritten unless the "-w" option is
1300
specified). This file can then be used in an indirect list of units.
1301
*Note Input units::. Note that if you use the recursive ("-r") option,
1302
it is more efficient to create the list of units once and then use the
1303
indirect file than to specify all applicable units each time AdaControl
1304
is run.
1305
1306
1307
File: adacontrol_ug.info, Node: Optimizing AdaControl, Next: In case of trouble, Prev: Helpful utilities, Up: Program Usage
1308
1309
3.8 Optimizing AdaControl
1310
==========================
1311
1312
There are many factors that may influence dramatically the speed of
1313
AdaControl when processing many units. For example, on our canonical
1314
test (same rules, same units), the extreme points for execution time
1315
were 111s. vs 13s.! Unfortunately, this seems to depend on a number of
1316
parameters that are beyond AdaControl's control, like the relative
1317
speed of the CPU to the speed of the hard-disk, or the caching strategy
1318
of the file system.
1319
1320
This section will give some hints that may help you increase the
1321
speed of AdaControl, but it will not change the output of the program;
1322
you don't really need to read it if you just use AdaControl
1323
occasionnally. This section is concerned only with the GNAT
1324
implementation of ASIS; other implementations work differently.
1325
1326
Bear in mind that the best strategy depends heavily on how your
1327
program is organized, and on the particular OS and hardware you are
1328
using. Therefore, no general rule can be given, you'll have to
1329
experiment yourself. Hint: if you specify the "-v" option to
1330
AdaControl, it will print in the end the elapsed time for running the
1331
tests; this is very helpful to make timing comparisons.
1332
1333
Note: all options described in this section are ASIS options, i.e.
1334
they must appear last on the command line, after a "--".
1335
1336
* Menu:
1337
1338
* Tree files and the ASIS context::
1339
* Choosing an appropriate combination of options::
1340
1341
1342
File: adacontrol_ug.info, Node: Tree files and the ASIS context, Next: Choosing an appropriate combination of options, Prev: Optimizing AdaControl, Up: Optimizing AdaControl
1343
1344
3.8.1 Tree files and the ASIS context
1345
-------------------------------------
1346
1347
Since AdaControl is an ASIS application, it is useful to explain here
1348
how ASIS works. ASIS (and therefore AdaControl) works on a set of units
1349
constituting a "context". Any reference to an Ada entity which is not
1350
in the context (nor automatically added, see below) will be ignored;
1351
especially, if you specify to AdaControl the name of a unit which is
1352
not included in the current context, the unit will simply not be
1353
processed.
1354
1355
ASIS works by exploring tree files (same name as the corresponding
1356
Ada unit, with a ".adt" extension), which are "predigested" views of
1357
the corresponding Ada units. Such tree files are obtained by compiling
1358
the units with the "-gnatc -gnatt" options. Alternatively, the tree
1359
files can be generated automatically when needed.
1360
1361
A context in ASIS-for-Gnat is a set of tree files. Which trees are
1362
part of the context is defined by the "-C" option:
1363
* -C1 Only one tree makes up the context. The name of the tree file
1364
must follow the option.
1365
1366
* -CN Several explicit trees make up the context. The name of the
1367
tree files must follow the option.
1368
1369
* -CA All available trees make up the context. These are the tree
1370
files found in the current directory, and in any directory given
1371
with a "-T" option (which works like the "-I" option, but for tree
1372
files instead of source files).
1373
1374
The "-F" option specifies what to do if the program tries to access
1375
an Ada unit which is not part of the context:
1376
* -FT Only consider tree files, do not attempt to compile units
1377
on-the-fly
1378
1379
* -FS Always compile units on-the-fly, ignore existing tree files
1380
1381
* -FM Compile on-the-fly units for which there is no already existing
1382
tree file
1383
Note that "-FT" is the only allowed mode, and must be specified,
1384
with the "-C1" and "-CN" options.
1385
1386
The default combination used by AdaControl is "-CA -FM".
1387
1388
1389
File: adacontrol_ug.info, Node: Choosing an appropriate combination of options, Prev: Tree files and the ASIS context, Up: Optimizing AdaControl
1390
1391
3.8.2 Choosing an appropriate combination of options
1392
----------------------------------------------------
1393
1394
In order to optimize the use of AdaControl, it is important to remember
1395
that reading tree files is a time-consuming operation. On the other
1396
hand, a single tree file contains not only information for the
1397
corresponding unit, but also for all units that the given unit depends
1398
on. Moreover, our measures showed that reading an existing tree file
1399
may be slower than compiling the corresponding unit on-the-fly (but
1400
once again, YMMV).
1401
1402
Note also that the "-r" option (recursive mode) of AdaControl
1403
implies an extra pass over the whole program tree to determine the
1404
necessary units.
1405
1406
Here are some hints to help you find the most efficient combination
1407
of options.
1408
* If you want to run AdaControl on all units of your program, use the
1409
"-D" option to create a file containing the list of all required
1410
units, then use this file as an indirect file.
1411
1412
* When using an indirect file, the order in which units are given may
1413
influence the speed of the program. As a rule of thumb, units that
1414
are closely related should appear close to each other in the file.
1415
A good starting point is to sort the file in alphabetical order:
1416
this way, child units will appear immediately after their parent.
1417
You can then reorder units, and measure if it has a significant
1418
effect on speed.
1419
1420
* If you want to check a unit individually, try using the "-C1"
1421
option (especially if the current directory contains many tree
1422
files from previous runs). Remember that you must specify the unit
1423
to check to AdaControl, and the tree file to ASIS. I.e., if you
1424
want to check the unit "Example", the command line should look
1425
like:
1426
adactl -f rules_file.aru example -- -FT -C1 example.adt
1427
provided the tree file already exists.
1428
1429
* For each strategy, first run AdaControl with the default options
1430
(which will create all necessary tree files). Compare execution
1431
time with the one you get with "-FT" and "-FS". This will tell you
1432
if compiling on-the-fly is more efficient than loading tree files,
1433
or not.
1434
1435
1436
File: adacontrol_ug.info, Node: In case of trouble, Prev: Optimizing AdaControl, Up: Program Usage
1437
1438
3.9 In case of trouble
1439
======================
1440
1441
Like any sophisticated piece of software, AdaControl may fail when
1442
encountering some special case of construct. ASIS may also fail
1443
occasionnally; actually, we discovered several ASIS bugs during the
1444
development of AdaControl. These were reported to ACT, and have been
1445
corrected in the wavefront version of GNAT - but you may be using an
1446
earlier version. In this case, try to upgrade to a newer version of
1447
ASIS. If an AdaControl or ASIS problem is not yet solved, AdaControl is
1448
designed in such a way that an occasionnal bug won't prevent you from
1449
using it.
1450
1451
If AdaControl detects an unexpected exception during the processing
1452
of a unit (an ASIS error or an internal error), it will abandon the
1453
unit, clean up everything, and go on processing the remaining units.
1454
This way, an error due to a special case in a unit will not affect the
1455
processing of other units. AdaControl will return a Status of 10 in
1456
this case.
1457
1458
However, if it is run with the "-x" option (eXit on error), it will
1459
stop immediately, and no further processing will happen.
1460
1461
If you don't want the garbage from a failing rule to pollute your
1462
report, you may chose to disable the rule for the unit that has a
1463
problem. *Note Inhibit command::.
1464
1465
If you encounter a problem while using AdaControl, you are very
1466
welcome to report it to rosen@adalog.fr. Please include the exact rule
1467
and the unit that caused the problem, as well as the captured output of
1468
the program (with "-d" option).
1469
1470
1471
File: adacontrol_ug.info, Node: Rules Usage, Next: Examples of using AdaControl for common programming rules, Prev: Program Usage, Up: Top
1472
1473
4 Rules Usage
1474
*************
1475
1476
This chapter describes each rule currently provided by AdaControl. Note
1477
that the `rules' directory of the distribution contains a file named
1478
`verif.aru' that contains an example of a set of rules appropriate to
1479
check on almost any software.
1480
1481
A general limitation applies to all rules. AdaControl is a static
1482
checking tool, and therefore cannot check usages that depend on
1483
run-time values. For example, it is not possible to check rules
1484
applying to an entity when this entity is aliased and accessed through
1485
an access value, or rules applying to subprogram calls when the call is
1486
a dispatching call.
1487
1488
* Menu:
1489
1490
* Allocators::
1491
* Declarations::
1492
* Default_Parameter::
1493
* Entities::
1494
* Entity_Inside_Exception::
1495
* Exception_Propagation::
1496
* Instantiations::
1497
* Local_Hiding::
1498
* Local_Instantiation::
1499
* Max_Nesting::
1500
* Naming_Convention::
1501
* No_Closing_Name::
1502
* Not_Elaboration_Calls::
1503
* Parameter_Aliasing::
1504
* Pragmas::
1505
* Real_Operators::
1506
* Representation_Clauses::
1507
* Side_Effect_Parameters::
1508
* Silent_Exceptions::
1509
* Simplifiable_Expressions::
1510
* Specification_Objects::
1511
* Statements::
1512
* Unnecessary_Use_Clause::
1513
* Use_Clauses::
1514
* When_Others_Null::
1515
1516
1517
File: adacontrol_ug.info, Node: Allocators, Next: Declarations, Prev: Rules Usage, Up: Rules Usage
1518
1519
4.1 Allocators
1520
==============
1521
1522
4.1.1 Syntax
1523
------------
1524
1525
<check|search|count> allocators [(<type name list>)];
1526
1527
4.1.2 Action
1528
------------
1529
1530
This rule controls usage of allocators. If type names are given, only
1531
allocators whose allocated type is mentioned are controlled, otherwise
1532
all allocators are controlled. This rule is especially useful for
1533
finding memory leaks, since it tells all the places where dynamic
1534
allocation occurs.
1535
1536
Ex:
1537
search allocators (standard.string);
1538
1539
4.1.3 Tips
1540
----------
1541
1542
If the allocated type is `T'Base' or `T'Class', it will currently be
1543
found as T. This can be improved in the future.
1544
1545
1546
File: adacontrol_ug.info, Node: Declarations, Next: Default_Parameter, Prev: Allocators, Up: Rules Usage
1547
1548
4.2 Declarations
1549
================
1550
1551
4.2.1 Syntax
1552
------------
1553
1554
<check|search|count> declarations (Declaration_kw {, Declaration_kw};
1555
Declaration_kw ::= access | access_subprogram | aliased |
1556
exception | task | tagged
1557
1558
4.2.2 action
1559
------------
1560
1561
This rule controls usage of certain Ada declarations. Declaration
1562
keywords that are Ada keywords match the corresponding Ada
1563
declarations. Note that `task' will match task type declarations as
1564
well as single tasks declarations; `access' will match all access type
1565
declarations, while `access_subprogram' will match only access to
1566
procedure or function declarations.
1567
1568
Ex:
1569
search declarations (task, exception);
1570
1571
1572
File: adacontrol_ug.info, Node: Default_Parameter, Next: Entities, Prev: Declarations, Up: Rules Usage
1573
1574
4.3 Default_Parameter
1575
=====================
1576
1577
4.3.1 Syntax
1578
------------
1579
1580
<check|search|count> default_parameter
1581
(<entity>, <formal name>, ["not"] "used" );
1582
1583
4.3.2 Action
1584
------------
1585
1586
This rule controls subprogram calls or generic instantiations that use
1587
(or conversely don't use) the default value for the indicated
1588
parameter. If a subprogram is called, or a generic instantiated, whose
1589
name matches <entity>, and it has a formal whose names is <formal
1590
name>, then:
1591
* If the string `used' (case irrelevant) is given as the third
1592
parameter, the rule is fired if there is no corresponding actual
1593
parameter (i.e. the default value is used for the parameter).
1594
1595
* If the string `not used' (case irrelevant) is given as the third
1596
parameter, the rule is fired if there is an explicit corresponding
1597
actual parameter (i.e. the default is not used for the parameter).
1598
1599
* If the string given as the third parameter is anything else, it is
1600
an error.
1601
1602
Ex:
1603
search default_parameter (P, X, used);
1604
search default_parameter (P, Y, not used);
1605
1606
4.3.3 Limitations
1607
-----------------
1608
1609
Due to an unimplemented feature under some versions of ASIS-for-Gnat,
1610
this rule may give an ASIS error (ASIS_FAILED, with a diagnosis of "Not
1611
Implemented Query" if used for subprogram calls. It allways works OK
1612
with instantiations.
1613
1614
1615
File: adacontrol_ug.info, Node: Entities, Next: Entity_Inside_Exception, Prev: Default_Parameter, Up: Rules Usage
1616
1617
4.4 Entities
1618
============
1619
1620
4.4.1 Syntax
1621
------------
1622
1623
<check|search|count> entities (<name list>);
1624
1625
4.4.2 Action
1626
------------
1627
1628
This rule controls all uses of the indicated entities. It is not
1629
intended to replace cross-references, but can be quite handy to check,
1630
for example, that a program does not contain any more calls to
1631
debugging procedures before fielding it.
1632
1633
Ex:
1634
search entities (Debug.Trace);
1635
1636
4.4.3 Tips
1637
----------
1638
1639
This rule can also be used to check for all occurrences of certain
1640
attributes with the "`all <Attribute>'" syntax. For example, the
1641
following will report on any usage of `'Unchecked_Access':
1642
check entities (all 'Unchecked_Access);
1643
1644
In certain contexts, only a limited set of the Ada predefined units
1645
is allowed. The `rules' directory of Adacontrol contains a file named
1646
`no_standard_unit.aru'. This file contains an Entity rule that forbids
1647
the use of any predefined Ada unit. Comment out the lines for the units
1648
that you want to allow. You can then simply "source" this files from
1649
your own rule file (or copy the content) if you want to disallow other
1650
units.
1651
1652
1653
File: adacontrol_ug.info, Node: Entity_Inside_Exception, Next: Exception_Propagation, Prev: Entities, Up: Rules Usage
1654
1655
4.5 Entity_Inside_Exception
1656
===========================
1657
1658
4.5.1 Syntax
1659
------------
1660
1661
<check|search|count> entity_inside_exception (<name list>);
1662
1663
4.5.2 Action
1664
------------
1665
1666
This rule controls exception handlers that contain references to one or
1667
several Ada entities specified as parameters.
1668
1669
Ex:
1670
check entity_inside_exception (ada.text_io.put_line);
1671
1672
1673
File: adacontrol_ug.info, Node: Exception_Propagation, Next: Instantiations, Prev: Entity_Inside_Exception, Up: Rules Usage
1674
1675
4.6 Exception_Propagation
1676
=========================
1677
1678
4.6.1 Syntax
1679
------------
1680
1681
<check|search|count> exception_propagation
1682
(interface, <convention> {, <convention> });
1683
<check|search|count> exception_propagation
1684
(parameter, <parameter name> {, <parameter name>});
1685
<check|search|count> exception_propagation
1686
(task);
1687
1688
4.6.2 Action
1689
------------
1690
1691
This rule controls subprograms or tasks that can propagate exceptions,
1692
while being used in contexts where it is desirable to ensure that no
1693
exception can be propagated. A subprogram or task is considered as not
1694
propagating if:
1695
1. it has an exception handlers with a "`when others'" choice
1696
1697
2. no exception handler contains a `raise' statement, nor any call to
1698
`Ada.Exception.Raise_Exception' or
1699
`Ada.Exception.Reraise_Occurrence'.
1700
1701
It is dangerous to call an Ada subprogram that can propagate
1702
exceptions from a language that has no exception (and especially C).
1703
Therefore any such subprogram should have a "catch-all" exception
1704
handler. In its first form, the rule analyzes all subprograms to which
1705
an `Interface' or `Export' pragma applies (with the given
1706
convention(s)), and reports on those that can propagate exceptions.
1707
1708
Moreover, many systems (typically windowing systems) use call-back
1709
subprograms. Although the native interface is generally hidden behind
1710
an Ada binding, the call-back subprograms will eventually be called
1711
from another language. In its second form, the rule is given one or
1712
more fully qualified formal parameter names (i.e. in the form of the
1713
parameter name prefixed by the full name of its subprogram, see *Note
1714
Specifying an Ada entity name::). The rule will report on any
1715
subprogram that can propagate exceptions and is used as the prefix of a
1716
`'Access' or `'Address' attribute that appears as part of an actual
1717
value for the indicated formal. Similarly, the indicated formal can
1718
also be the name of a formal procedure or function of a generic. In
1719
this case, the rule will report on any subprogram that can propagate
1720
exceptions and is used as an actual in an instantiation for the given
1721
formal.
1722
1723
Finally, since tasks die silently if an exception is propagated out
1724
of their body, it is generally desirable to ensure that every task has
1725
an exception handler that (at least) reports that the task is being
1726
completed due to an exception.
1727
1728
Ex:
1729
check exception_propagation (interface, C);
1730
check exception_propagation (parameter, Pack.Register.CB);
1731
check exception_propagation (task);
1732
1733
The first line will report on any subprogram to which a `pragma
1734
Interface (C,...)' applies that can propagate exceptions.
1735
1736
If `Proc' is a procedure that can propagate exceptions, the second
1737
line will report on every call like:
1738
Pack.Register (CB => Proc'Access);
1739
1740
The third line will report on any task that can terminate silently
1741
due to an unhandled exception.
1742
1743
4.6.3 Tips
1744
----------
1745
1746
Note that the registration procedure can be designated by an access
1747
type, but in this case, use the name of the formal for the access type.
1748
For example, given:
1749
package Pack is
1750
type Acc_Proc is access procedure;
1751
type Acc_Reg is access procedure (CB : Acc_Proc);
1752
...
1753
Ptr : Acc_Reg := ...;
1754
1755
You can give a rule such as:
1756
check exception_propagation (parameter, Pack.Acc_Reg.CB);
1757
All procedures registered by a call to `Pack.Ptr.all' will be
1758
considered.
1759
1760
4.6.4 Limitations
1761
-----------------
1762
1763
An exception may be raised in a subprogram considered as not
1764
propagating by this rule, if an exception handler calls a subprogram
1765
that propagates an exception.
1766
1767
The rule will not consider subprograms that are not statically known
1768
(i.e. if a subprogram is registered through a dereference of a pointer
1769
to subprogram), like in the following exampe:
1770
Pack.Register (CB => Pointer.all'Access);
1771
1772
Due to a weakness of the ASIS standard, references to subprograms
1773
that appear in dispatching calls are not considered. This limitation
1774
will be removed as soon as we find a way to work around this problem,
1775
but the issue is quite difficult!
1776
1777
1778
File: adacontrol_ug.info, Node: Instantiations, Next: Local_Hiding, Prev: Exception_Propagation, Up: Rules Usage
1779
1780
4.7 Instantiations
1781
==================
1782
1783
4.7.1 Syntax
1784
------------
1785
1786
<check|search|count> instantiations (<generic name> {, <entity name> | <>});
1787
1788
4.7.2 Action
1789
------------
1790
1791
This rule controls all instantiations of a generic, or only
1792
instantiations that are made with specific values of the parameters.
1793
1794
An instantiation matches if either:
1795
1. No entity name is given in the rule
1796
1797
2. The entity names given are the same as the first parameters of the
1798
instantiation (i.e. there can be more actual parameters in the
1799
instantiation than specified in the rule). A box `<>' can be given
1800
instead of an entity name, in which case it will match any actual
1801
parameter.
1802
1803
If an actual is an expression (which is possible only for a formal
1804
`in' object), it cannot be matched.
1805
1806
Ex:
1807
search instantiations (ada.unchecked_deallocation);
1808
check instantiations (ada.unchecked_conversion, standard.string);
1809
check instantiations (ada.unchecked_conversion, <>, standard.string);
1810
The first example searches for all instantiations of
1811
`Ada.Unchecked_Deallocation'; the second one checks instantiations of
1812
`Ada.Unchecked_Conversion' where the first parameter is `String'
1813
(ignoring the second parameter), while the third example checks
1814
instantiations of `Ada.Unchecked_Conversion' where the second parameter
1815
is `String' (ignoring the first parameter).
1816
1817
4.7.3 Tips
1818
----------
1819
1820
It is often useful to check that a generic is instantiated only once
1821
(at least for a given type) in a project. For example, a project may
1822
have a special service in charge of releasing pointers to strings; it
1823
may be useful to check that `Unchecked_Deallocation' is not
1824
instantiated for `String' anywhere else.
1825
1826
Note that the report message for this rule counts how many matches
1827
are found; a first solution is to search for instantiations of
1828
`Unchecked_Deallocation' and verify manually that the count is 1.
1829
1830
Another solution is to disable the check for the rule at the place
1831
where it is allowed, and then do a check; if there are other
1832
instantiations, they will come out as errors.
1833
1834
1835
File: adacontrol_ug.info, Node: Local_Hiding, Next: Local_Instantiation, Prev: Instantiations, Up: Rules Usage
1836
1837
4.8 Local_Hiding
1838
================
1839
1840
4.8.1 Syntax
1841
------------
1842
1843
<check|search|count> local_hiding;
1844
1845
4.8.2 Action
1846
------------
1847
1848
This rule controls declarations that hide an outer declaration with the
1849
same name (and parameter and result type profile, if both are
1850
overloadable constructs). Since this rule has no parameters, it can be
1851
given only once (otherwise, it is an error).
1852
1853
Ex:
1854
search local_hiding;
1855
1856
1857
File: adacontrol_ug.info, Node: Local_Instantiation, Next: Max_Nesting, Prev: Local_Hiding, Up: Rules Usage
1858
1859
4.9 Local_Instantiation
1860
=======================
1861
1862
4.9.1 Syntax
1863
------------
1864
1865
<check|search|count> local_instantiation (<generic name list>);
1866
1867
4.9.2 Action
1868
------------
1869
1870
This rule controls instantiations that are done in a local scope (i.e.
1871
not at library level in a library package, or a subpackage of a library
1872
package). Instantiations that appear in a generic package are not
1873
flagged (unless the generic package is itself in a local scope).
1874
1875
Ex:
1876
search local_instantiation (ada.unchecked_deallocation);
1877
1878
1879
File: adacontrol_ug.info, Node: Max_Nesting, Next: Naming_Convention, Prev: Local_Instantiation, Up: Rules Usage
1880
1881
4.10 Max_Nesting
1882
================
1883
1884
4.10.1 Syntax
1885
-------------
1886
1887
<check|search|count> max_nesting (<max allowed depth>);
1888
1889
4.10.2 Action
1890
-------------
1891
1892
This rule controls the nesting of declarative constructs (like
1893
subprograms, packages, generics, block statements...) that exceed a
1894
given depth. Nesting of statements (`loop', `case') is not considered.
1895
This rule can be given once for each of for check, search, and count.
1896
This way, it is possible to have a level considered a warning (search),
1897
and one considered an error (check). Of course, this makes sense only
1898
if the level for search is less than the one for check.
1899
1900
Ex:
1901
search max_nesting (5);
1902
check max_nesting (7);
1903
1904
1905
File: adacontrol_ug.info, Node: Naming_Convention, Next: No_Closing_Name, Prev: Max_Nesting, Up: Rules Usage
1906
1907
4.11 Naming_Convention
1908
======================
1909
1910
4.11.1 Syntax
1911
-------------
1912
1913
<check|search|count> naming_convention
1914
([root] <Filter_Kind>,
1915
[case_sensitive | case_insensitive] [not] "<Pattern>" {, ...});
1916
<Filter_Kind> ::= All |
1917
Type |
1918
Discrete_Type |
1919
Enumeration_Type |
1920
Integer_Type |
1921
Signed_Integer_Type |
1922
Modular_Integer_Type |
1923
Floating_Point_Type |
1924
Fixed_Point_Type |
1925
Binary_Fixed_Point_Type |
1926
Decimal_Fixed_Point_Type |
1927
Array_Type |
1928
Record_Type |
1929
Regular_Record_Type |
1930
Tagged_Type |
1931
Class_Type |
1932
Access_Type |
1933
Access_To_Regular_Type |
1934
Access_To_Tagged_Type |
1935
Access_To_Class_Type |
1936
Access_To_SP_Type |
1937
Access_To_Task_Type |
1938
Access_To_Protected_Type |
1939
Private_Type |
1940
Private_Extension |
1941
Generic_Formal_Type |
1942
Variable |
1943
Regular_Variable |
1944
Field |
1945
Discriminant |
1946
Record_Field |
1947
Protected_Field |
1948
Procedure_Formal_Out |
1949
Procedure_Formal_In_Out |
1950
Generic_Formal_In_Out |
1951
Constant |
1952
Regular_Constant |
1953
Named_Number |
1954
Integer_Number |
1955
Real_Number |
1956
Enumeration |
1957
Sp_Formal_In |
1958
Generic_Formal_In |
1959
Loop_Control |
1960
Occurrence_Name |
1961
Entry_Index |
1962
Label |
1963
Stmt_Name |
1964
Loop_Name |
1965
Block_Name |
1966
Subprogram |
1967
Procedure |
1968
Regular_Procedure |
1969
Protected_Procedure |
1970
Generic_Formal_Procedure |
1971
Function |
1972
Regular_Function |
1973
Protected_Function |
1974
Generic_Formal_Function |
1975
Entry |
1976
Task_Entry |
1977
Protected_Entry |
1978
Package |
1979
Regular_Package |
1980
Generic_Formal_Package |
1981
Task |
1982
Task_Type |
1983
Task_Object |
1984
Protected |
1985
Protected_Type |
1986
Protected_Object |
1987
Exception |
1988
Generic |
1989
Generic_Package |
1990
Generic_Sp |
1991
Generic_Procedure |
1992
Generic_Function
1993
1994
4.11.2 Action
1995
-------------
1996
1997
This rule controls the declaration of identifiers that do not follow
1998
the project's naming conventions. The first parameter defines the kind
1999
of declaration to which the rule is applicable, and other parameters
2000
define patterns, using the full Regexp syntax. Please refer to the
2001
`regexp' reference manual, or to the comments in file `gnat-regpat.ads'
2002
for details. If a pattern is preceded by "not", then the pattern must
2003
not be matched (i.e. the rule is fired if there is a match). Note that
2004
the pattern needs not include any wildcard, but if it does, it must be
2005
enclosed in quotes. If "case_sensitive" is specified, pattern matching
2006
considers casing. Otherwise (default or "case_insensitive"), casing is
2007
irrelevant. Note that the rule checks the name only at the place where
2008
it is declared; casing might be different when the name is used later.
2009
2010
The rule will be activated if an identifier is declared that does not
2011
match any of the "positive" patterns (the ones without "not"), or if it
2012
matches any of the "negative" patterns (the ones with a "not"). If only
2013
negative patterns are given, it is implicitely assumed that all other
2014
identifiers are OK. In other words, accepted identifiers must have the
2015
form of (at least) one of the "positive" patterns (if any), but not the
2016
form of one of the "negative" patterns.
2017
2018
The filter kinds are organized hierarchically, as reflected in the
2019
syntax above. To be valid, the name must match the patterns specified
2020
for its own filter, and for all filters above it in the hierarchy. For
2021
example, a modular type declaration must follow the rules (if
2022
specified) for "all", "type","discrete_type", "integer_type" and
2023
"modular_integer_type". However, if a filter kind is preceded by
2024
"root", rules above it in the hierarchy are not considered (neither for
2025
itself not its children). This is useful to make exceptions to a more
2026
general rule.
2027
2028
It is of course not necessary to specify all the filter kinds, nor to
2029
specify filters down to the deepest level; if you specify a rule for
2030
"type", it will be applied to all type declarations, whether there is a
2031
more specific rule or not.
2032
2033
For renamings, the applicable rule is the one for the renamed
2034
entity. Similarly, subtypes and derived types must follow the rule for
2035
their respective original (full) type. Incomplete type declarations are
2036
not checked, since their corresponding full declaration is (normally)
2037
checked. Private types (including of course the full declaration of a
2038
private type) follow the rule for private types, not the rules for
2039
their full type view (otherwise it would be privacy breaking).
2040
2041
Ex:
2042
-- All identifiers must have at least 3 characters:
2043
check naming_convention (all, "...");
2044
2045
-- Predefined name is forbidden:
2046
check naming_convention (all, not Integer);
2047
2048
-- Types must either start or end with T
2049
check naming_convention (type, case_sensitive "^T_",
2050
case_sensitive "_T$");
2051
2052
-- Exception to the rule for "all":
2053
-- No minimum length for "for loop" identifiers
2054
check naming_convention (root loop_parameter, ".");
2055
2056
-- "Upper_Initials" naming convention:
2057
check naming_convention
2058
(all, case_sensitive "^[A-Z][a-z0-9]*(_[A-Z0-9][a-z0-9]*)*$");
2059
2060
4.11.3 Tips
2061
-----------
2062
2063
Remember that a Regexp matches if the pattern matches any part of the
2064
identifier. Use "^" and "$" to match the beginning (resp. end) of the
2065
name, or both.
2066
2067
"class_type" is applicable to subtypes that designate a class-wide
2068
type. Similarly, "access_to_class_type" is applicable to access types
2069
whose designated type is class-wide.
2070
2071
The `rules' directory of Adacontrol contains two files named
2072
`no_standard_entity.aru' and `no_system_entity.aru'. These are files
2073
that contain a naming_convention rule that forbids the declaration of
2074
names declared in packages `Standard' and `System', respectively. You
2075
can simply "source" these files from your own rule file (or copy the
2076
content) if you want to disallow these identifiers.
2077
2078
Like usual, naming_convention rule can be given multiple times, and
2079
can be disabled. However, consider the following:
2080
Rule1 : check naming_convention (constant, "^c_");
2081
Rule2 : check naming_convention (constant, "^const_");
2082
The rule will trigger if a constant is declared that does not start
2083
with either "c_" or "const_". But here, we have two different rule
2084
labels. The message will refer to the first label encountered in the
2085
rule file; this is the label that must be mentionned in a disabling
2086
comment, unless you simply disable "naming_convention".
2087
2088
4.11.4 Limitations
2089
------------------
2090
2091
This rule does not support wide characters outside the basic Latin-1
2092
set.
2093
2094
If you compiled with the `Portable_String_Matching' package, only
2095
basic ("*" and "?") wildcards are available.
2096
2097
2098
File: adacontrol_ug.info, Node: No_Closing_Name, Next: Not_Elaboration_Calls, Prev: Naming_Convention, Up: Rules Usage
2099
2100
4.12 No_Closing_Name
2101
====================
2102
2103
4.12.1 Syntax
2104
-------------
2105
2106
<check|search|count> no_closing_name [(<acceptable length>)];
2107
2108
4.12.2 Action
2109
-------------
2110
2111
This rule controls declarations, like package or subprograms, that
2112
allow (but do not require) repeating the name at the end of the
2113
declaration, and where the closing name is omitted (which is considered
2114
bad style in general). However, it can be acceptable to allow the
2115
omission of closing names for very short constructs; therefore this
2116
rule has an optional parameter specifying the maximum number of lines
2117
of a construct for which omitting the closing name is allowed. This
2118
rule can be given only once for each of check, search and count. This
2119
way, it is possible to have a length considered a warning (search), and
2120
one considered an error (check). Of course, this makes sense only if
2121
the length for search is less than the one for check. If no length is
2122
specified, all occurrences of missing closing names are signaled.
2123
2124
Ex:
2125
search no_closing_name;
2126
check no_closing_name (5);
2127
2128
2129
File: adacontrol_ug.info, Node: Not_Elaboration_Calls, Next: Parameter_Aliasing, Prev: No_Closing_Name, Up: Rules Usage
2130
2131
4.13 Not_Elaboration_Calls
2132
==========================
2133
2134
4.13.1 Syntax
2135
-------------
2136
2137
<check|search|count> not_elaboration_calls (<subprogram name list>);
2138
2139
4.13.2 Action
2140
-------------
2141
2142
This rule controls subprogram calls (procedure, function or entry
2143
calls) that are performed at any time except during the elaboration of
2144
library packages.
2145
2146
Ex:
2147
search not_elaboration_calls (Data.Initialize);
2148
2149
4.13.3 Limitations
2150
------------------
2151
2152
Due to an (allowed by ASIS standard) limitation of ASIS-for-Gnat, the
2153
rule will not detect calls to subprograms that are implicitely defined,
2154
like calling a `"+"' on `Integer'. Fortunately, it is very unlikely
2155
that the user would want to forbid that kind of calls in
2156
non-elaboration code.
2157
2158
Note also that calls that cannot be statically determined, like calls
2159
to dispatching operations or calls through pointers to subprograms
2160
cannot be detected either.
2161
2162
2163
File: adacontrol_ug.info, Node: Parameter_Aliasing, Next: Pragmas, Prev: Not_Elaboration_Calls, Up: Rules Usage
2164
2165
4.14 Parameter_Aliasing
2166
=======================
2167
2168
4.14.1 Syntax
2169
-------------
2170
2171
<check|search|count> parameter_aliasing [(Certain | Possible | Unlikely)];
2172
2173
4.14.2 Action
2174
-------------
2175
2176
This rule controls aliased use of variables in subprogram calls.
2177
Specifically, this rule will identify calls where the same variable is
2178
given as an actual to more than one `out' or `in out' parameter, like
2179
in the following example:
2180
procedure Proc (X, Y : out Integer);
2181
...
2182
Proc (X => V, Y => V);
2183
2184
There are many cases where aliasing cannot be determined statically.
2185
The optional parameter specifies how aggressively the rule will check
2186
for possible aliasings. Possible values are (case irrelevant):
2187
* Certain (default): Only cases where aliasing is statically certain
2188
are output.
2189
2190
* Possible: In addition, cases where aliasing may occur depending on
2191
the value of an indexed component are output. These may or may not
2192
be true aliasing, depending on the algorithm. For example, given:
2193
Swap (Tab (I), Tab (J));
2194
there is no aliasing, unless `I' equals `J'.
2195
2196
If all expressions used for indexing in both variables are integer
2197
or enumeration litterals, the rule will be able to eliminate the
2198
diagnosis of aliasing (if the values are different). This does not
2199
cover all cases of static expressions, but will avoid unnecessary
2200
messages in cases like:
2201
Swap (Tab (1), Tab (2));
2202
2203
* Unlikely: In addition, cases where aliasing may occur due to access
2204
variables pointing to the same variable are output. These may or
2205
may not be true aliasing, depending on the algorithm, but should
2206
normally occur only as the result of very strange practices, like
2207
in the following example:
2208
type R is
2209
record
2210
X : aliased Integer;
2211
end record;
2212
X : R;
2213
Y : Access_All_Integer := R.X'access;
2214
...
2215
P (X, Y.all);
2216
There will be no false positive with "Certain". There will be no
2217
false negative with "Unlikely" (but many false positives). "Possible"
2218
is somewhere in-between.
2219
2220
The rule may be specified at most once for each value of the
2221
parameter. This allows for example to "check" for "Certain" and
2222
"search" for "Possible".
2223
2224
Ex:
2225
check parameter_aliasing;
2226
search parameter_aliasing (Possible);
2227
2228
Note that the rule is quite clever: it will consider partial aliasing
2229
(like a record variable as one parameter, and one of its components as
2230
another parameter), and will not be fooled by renamings.
2231
2232
4.14.3 Limitation
2233
-----------------
2234
2235
Due to a weakness of the ASIS standard, dispatching calls are not
2236
considered. This limitation will be removed as soon as we find a way to
2237
work around this problem, but the issue is quite difficult!
2238
2239
2240
File: adacontrol_ug.info, Node: Pragmas, Next: Real_Operators, Prev: Parameter_Aliasing, Up: Rules Usage
2241
2242
4.15 Pragmas
2243
============
2244
2245
4.15.1 Syntax
2246
-------------
2247
2248
<check|search|count> pragmas (nonstandard | <pragma name> {, ...});
2249
2250
4.15.2 Action
2251
-------------
2252
2253
This rule controls usage of one or several specific pragmas. If the
2254
special name "nonstandard" is given, then all implementation-defined
2255
and unrecognized pragmas will be controlled.
2256
2257
Ex:
2258
check pragmas (elaborate_all, elaborate_body);
2259
2260
2261
File: adacontrol_ug.info, Node: Real_Operators, Next: Representation_Clauses, Prev: Pragmas, Up: Rules Usage
2262
2263
4.16 Real_Operators
2264
===================
2265
2266
4.16.1 Syntax
2267
-------------
2268
2269
<check|search|count> real_operators;
2270
2271
4.16.2 Action
2272
-------------
2273
2274
This controls usage of exact equality or inequality ("=" or "/=")
2275
between real (floating point or fixed point) values.
2276
2277
Ex:
2278
check real_operators;
2279
2280
2281
File: adacontrol_ug.info, Node: Representation_Clauses, Next: Side_Effect_Parameters, Prev: Real_Operators, Up: Rules Usage
2282
2283
4.17 Representation_Clauses
2284
===========================
2285
2286
4.17.1 Syntax
2287
-------------
2288
2289
<check|search|count> representation_clauses
2290
[( at | at_mod | enumeration | record | <attribute>, ... )];
2291
2292
4.17.2 Action
2293
-------------
2294
2295
This rule controls usage of representation clause. Without parameter,
2296
it will control all representation clauses, otherwise it will control
2297
the representation clauses given as parameter.
2298
2299
"at" checks for address clauses given in Ada 83 style ("for XXX use
2300
at"). "at_mod" checks for alignment clauses given in Ada 83 style ("for
2301
T use record at mod XX;"). "enumeration" checks for enumeration
2302
representation clauses. "record" checks for record representation
2303
clauses. In addition to these keyword, any specifiable attribute can be
2304
given (including the initial ""'); the rule will check for a
2305
specification of this attribute. Note that double attributes (like
2306
"'CLASS'INPUT") can be given, and are considered different from the
2307
simple attribute ("'INPUT"). It is of course possible to specify both.
2308
2309
Ex:
2310
All_Addresses: check representation_clauses (at, 'address);
2311
All_Input: check representation_clauses ('input, 'class'input);
2312
count representation_clauses ('SIZE);
2313
2314
2315
File: adacontrol_ug.info, Node: Side_Effect_Parameters, Next: Silent_Exceptions, Prev: Representation_Clauses, Up: Rules Usage
2316
2317
4.18 Side_Effect_Parameters
2318
===========================
2319
2320
4.18.1 Syntax
2321
-------------
2322
2323
<check|search|count> Side_Effect_Parameters (<function name list>);
2324
2325
4.18.2 Action
2326
-------------
2327
2328
This controls subprogram calls or generic instantiations where
2329
different actual parameters call functions known to have side effects.
2330
This is dangerous practice, since correct behaviour may depend on a
2331
certain evaluation order of parameters, which is not specified by the
2332
language.
2333
2334
All functions mentionned as parameters in the rule are assumed to
2335
interfere, i.e. the rule will signal if any of these functions is
2336
called more than once in the parameters of a call.
2337
2338
It is allowed to give the name of a generic function, or of a
2339
function declared in a generic package; in this case, all functions
2340
resulting from instantiations of these generics will be considered.
2341
2342
In the case of renamings, you must give the name of the original
2343
function; the rule will work correctly if the call is made through a
2344
renaming of this function.
2345
2346
Ex:
2347
check side_effect_parameters (F1);
2348
check side_effect_parameters (G1, G2);
2349
2350
Here, F1 has a side effect, and the rule will signal if it is called
2351
more than once. G1 and G2 are assumed to interfere, and therefore the
2352
rule will signal if either is called more than once, or if both are
2353
called. However, having a call that mentions F1 and G2 is OK.
2354
2355
4.18.3 Limitation
2356
-----------------
2357
2358
Due to the size of internal structures, this rule may not be given more
2359
than 100 times.
2360
2361
Due to an unimplemented feature of ASIS-for-Gnat, this rule will not
2362
process defaulted parameters, and hence not detect interferences due to
2363
calling a side-effect function through the default value.
2364
2365
2366
File: adacontrol_ug.info, Node: Silent_Exceptions, Next: Simplifiable_Expressions, Prev: Side_Effect_Parameters, Up: Rules Usage
2367
2368
4.19 Silent_Exceptions
2369
======================
2370
2371
4.19.1 Syntax
2372
-------------
2373
2374
<check|search|count> Silent_Exceptions (<procedure name list>);
2375
2376
4.19.2 Action
2377
-------------
2378
2379
This rule controls exception handlers that can cause exceptions to
2380
silently disappear, i.e. handlers that do not call one of the given
2381
procedures (for example a reporting procedure) nor re-raise an
2382
exception. Entry calls are accepted as well as procedure calls.
2383
2384
This rule can be given once for each of check, search and count. This
2385
way, it is possible to have a level considered a warning (search), and
2386
one considered an error (check).
2387
2388
Ex:
2389
check silent_exceptions (reports.trace);
2390
2391
If the `raise' statements or procedure calls appear only in `if' or
2392
`case' statements, but not in all possible paths, or if they appear
2393
only in the body of `loop' statements, the rule will issue a message
2394
asking for a manual verification, since it cannot be statically
2395
determined whether the proper treatment happens in every case.
2396
2397
The procedures `Ada.Exceptions.Raise_Exception' and
2398
`Ada.Exceptions.Reraise_Occurrence' are automatically added to the list
2399
of procedures for both Check and Search, unless they are explicitely
2400
specified as a parameter in a rule. This way, it is possible to
2401
consider them as reporting procedures for Check (for example) and not
2402
for Search.
2403
2404
4.19.3 Limitations
2405
------------------
2406
2407
There are two cases that are not statically checkable, and thus may not
2408
be identified by this rule: if an exception is raised in an inner block
2409
statement and handled locally, and if the exception handler aborts the
2410
current task.
2411
2412
2413
File: adacontrol_ug.info, Node: Simplifiable_Expressions, Next: Specification_Objects, Prev: Silent_Exceptions, Up: Rules Usage
2414
2415
4.20 Simplifiable_Expressions
2416
=============================
2417
2418
4.20.1 Syntax
2419
-------------
2420
2421
<check|search|count> Simplifiable_Expressions [(keyword)];
2422
keyword ::= range | logical | logical_true | logical_false | parentheses
2423
2424
4.20.2 Action
2425
-------------
2426
2427
This rule controls expressions that can be simplified. The "range"
2428
parameter controls expressions of the form `T'First .. T'Last' that
2429
should be `T'range' (or even simply `T'). "logical_true" controls
2430
redundant boolean expressions of the form `<expr> = True' (or `/='),
2431
and "logical_false" does the same for comparisons with `false'.
2432
"logical" is the same as specifying both "logical_true" and
2433
"logical_false". "parentheses" controls unnecessary parentheses
2434
surrounding the expression of an "if" or "case" statement.
2435
2436
Ex:
2437
check simplifiable_expressions (range, logical);
2438
2439
2440
File: adacontrol_ug.info, Node: Specification_Objects, Next: Statements, Prev: Simplifiable_Expressions, Up: Rules Usage
2441
2442
4.21 Specification_Objects
2443
==========================
2444
2445
4.21.1 Syntax
2446
-------------
2447
2448
<check|search|count> specification_objects
2449
[( [not] constant|read|written|initialized {, ...})];
2450
2451
4.21.2 action
2452
-------------
2453
2454
This rule controls usage of objects (variables and constants) declared
2455
in (generic) package specifications. Variables are often discouraged in
2456
package specifications, or need at least some extra control. Constants
2457
that are never used (not even in the package itself) are also
2458
suspicious. Moreover, some useful compiler warnings (like those about
2459
variables that should be declared constants) are not output for
2460
variables declared in library packages (at least with GNAT). This rule
2461
can do the same thing, project wide.
2462
2463
By default (without any parameter), this rule will report about usage
2464
of each object declared in a package specification which is part of the
2465
processed units; usage of objects whose declaration is not processed
2466
(like, typically, elements declared in standard packages like
2467
`Ada.Text_IO', are not reported). The report includes the kind of
2468
package that declares the object (normal package, instantiation, or
2469
generic) and whether it is known to be initialized, read, and/or
2470
written. Variables of an access type and variables of an array type
2471
whose components are of an access type (or arrays of an access type,
2472
etc.) are always considered initialized, since they are initialized to
2473
`null' by the compiler. Some combinations give an extra useful message
2474
(for example, a variable which is initialized and read but not written
2475
will produce a "could be declared constant" message).
2476
2477
In the case of objects declared in generic packages, the rule will
2478
report on usage of the objects for each instantiation, as well as on
2479
global usage for the generic itself. Usage for an instantiation will
2480
include usage in the generic itself (i.e. if the generic writes to a
2481
variable, the variable will be marked as "written" for each
2482
instantiation). Usage for the generic itself is the union of all usages
2483
in all instantiations (i.e., if a variable from any instantiation is
2484
written to, the variable from the generic will be marked as written).
2485
Therefore, if the rule reports that a variable in a generic package can
2486
be declared constant, it means that no instance of this variable from
2487
any instantiation is being written to. But bear in mind that this can
2488
be trusted only if all units from the program are analyzed. *Note
2489
limitation::.
2490
2491
It is possible to specify as parameter(s) one or several of the
2492
keywords (case irrelevant) `constant' `read', `written', or
2493
`initialized', possibly preceded by `not'. The rule will output the
2494
information only for objects that match all the conditions given. The
2495
rule can be given once and only once for each combination of the
2496
parameters.
2497
2498
Ex:
2499
search specification_objects (not read);
2500
check specification_objects (not initialized, not written, read);
2501
2502
4.21.3 Tips
2503
-----------
2504
2505
An unspecified parameter in a rule stands for two rules (positive and
2506
negative form of the missing parameter). I.e.:
2507
search specification_objects (read, written);
2508
is the same as:
2509
search specification_objects (read, written, initialized);
2510
search specification_objects (read, written, not initialized);
2511
Therefore, the following example will complain on the second line
2512
that the rule has already been given for this combination of parameters:
2513
search specification_objects (read, written);
2514
search specification_objects (read, written, not initialized);
2515
2516
Constants will be reported only for rules that apply (implicitely or
2517
explicitely) to "initialized, not written" since this is guaranteed by
2518
the language. The message tells it is a constant, but does not report
2519
"initialized, not written". Use "not constant" if you don't want
2520
reports about constants. Note that the notion of constants for this
2521
rule includes named numbers.
2522
2523
4.21.4 Limitation
2524
-----------------
2525
2526
The report of this rule is output at the end of the run, and is
2527
meaningful only for the units that have been processed; i.e., if it
2528
reports "variable not read", it should be understood as "not read by
2529
the units given".
2530
2531
In order to have meaningful results, it is therefore advisable to use
2532
this rule on the complete closure of the program.
2533
2534
Due to a weakness of the ASIS standard, specification variables that
2535
appear as [`in'] `out' parameters in dispatching calls are not marked
2536
as "written". This limitation will be removed as soon as we find a way
2537
to work around this problem, but the issue is quite difficult!
2538
2539
2540
File: adacontrol_ug.info, Node: Statements, Next: Unnecessary_Use_Clause, Prev: Specification_Objects, Up: Rules Usage
2541
2542
4.22 Statements
2543
===============
2544
2545
4.22.1 Syntax
2546
-------------
2547
2548
<check|search|count> statements (statement_kw {, statement_kw};
2549
Statement_kw ::= abort | asynchronous_select | case_others | delay |
2550
delay_until | exit | goto | raise | requeue
2551
2552
4.22.2 action
2553
-------------
2554
2555
This rule controls usage of certain Ada statements. Statement keywords
2556
that are Ada keywords match the corresponding Ada statements; note that
2557
`delay' will match only relative `delay' statements (i.e. it will not
2558
match the `delay until' statement). `asynchronous_select' matches the
2559
`select' ... `then abort' statement. `case_others' matches a `when
2560
others' path in a `case' statement. `unnamed_exit' matches an `exit'
2561
statement without a loop name that exits from a named loop.
2562
2563
Ex:
2564
search statements (delay);
2565
check statements (goto, abort);
2566
2567
2568
File: adacontrol_ug.info, Node: Unnecessary_Use_Clause, Next: Use_Clauses, Prev: Statements, Up: Rules Usage
2569
2570
4.23 Unnecessary_Use_Clause
2571
===========================
2572
2573
4.23.1 Syntax
2574
-------------
2575
2576
<check|search|count> unnecessary_use_clause;
2577
2578
4.23.2 Action
2579
-------------
2580
2581
This rule controls `use' clauses that do not serve any purpose and can
2582
safely be removed. This happens in two cases:
2583
* A `use' clause is given, but no element from the corresponding
2584
package is mentionned in its scope.
2585
2586
* A `use' clause is given within the scope of an enclosing `use'
2587
clause for the same package.
2588
2589
In the first case, just remove the `use' clause. In the second case,
2590
the rule will signal the location of the enclosing `use' clause. If you
2591
also have a message that the outer `use' clause is unnecessary, this
2592
means that all references to the package appear inside the inner `use'
2593
clauses, and that the outer one can be removed. If not, you can either
2594
remove the inner `use' clauses, or remove the outer one and add more
2595
local `use' clauses where necessary.
2596
2597
This rule will also signal `use' clauses given in a package
2598
specification that can safely be moved to the body. Since this rule has
2599
no parameters, it can be given only once (otherwise, it is an error).
2600
2601
Ex:
2602
search unnecessary_use_clause;
2603
2604
4.23.3 Limitations
2605
------------------
2606
2607
There are some rare cases where the rule may signal that a `use' clause
2608
is not necessary, where it actually is. There is no risk associated to
2609
this since if you remove the `use' clause, the program will not compile.
2610
2611
The first one comes from a limitation of the ASIS standard: if the
2612
only use of the `use' clause is for making the "root" definition of a
2613
dispatching call visible.
2614
2615
The second one comes from a limitation in ASIS-for-Gnat. This happens
2616
when the only use of the `use' clause is for making an implicitely
2617
declared operation (an operation which is declared by the compiler as
2618
part of a type derivation) visible, and when:
2619
* the operation is the target of a renaming declaration;
2620
2621
* or the operation is passed as an actual to a generic instantiation;
2622
2623
* or all operands of the operation are universal (i.e. untyped).
2624
2625
Since these problems come from intrinsic limitations of ASIS, there
2626
is nothing we can do about it. When this happens, you can disable the
2627
unnecessary_use_clause rule using the line (or block) disabling
2628
feature. *Note Disabling rules::. Note that for the third alternative
2629
of the second case, you can also qualify one of the parameters, so it
2630
is not universal any more.
2631
2632
2633
File: adacontrol_ug.info, Node: Use_Clauses, Next: When_Others_Null, Prev: Unnecessary_Use_Clause, Up: Rules Usage
2634
2635
4.24 Use_Clauses
2636
================
2637
2638
4.24.1 Syntax
2639
-------------
2640
2641
<check|search|count> use_clauses (<package name list>);
2642
2643
4.24.2 Action
2644
-------------
2645
2646
This rule controls usage of use clauses, except for the ones that name
2647
one of the mentioned packages. It is therefore possible to allow use
2648
clauses just for certain packages.
2649
2650
This rule can be given at most once for each of check, search and
2651
count. This way, it is possible to have a level considered a warning
2652
(search), and one considered an error (check).
2653
2654
Ex:
2655
check use_clauses (Ada.Text_IO, Ada.Wide_Text_IO);
2656
2657
2658
File: adacontrol_ug.info, Node: When_Others_Null, Prev: Use_Clauses, Up: Rules Usage
2659
2660
4.25 When_Others_Null
2661
=====================
2662
2663
4.25.1 Syntax
2664
-------------
2665
2666
<check|search|count> when_others_null [(exception | case, ...)]
2667
2668
4.25.2 Action
2669
-------------
2670
2671
This rule controls "when others" case alternatives or exception
2672
handlers that contain only null statements. If no parameter is
2673
specified, both exception handlers and case statements are searched.
2674
Otherwise, it is possible to specify "exception" to search only
2675
exception handlers, or "case" to search only case statements.
2676
2677
This rule can be specified at most twice, once for "case" and once
2678
for "exception".
2679
2680
Ex:
2681
check when_others_null (exception);
2682
search when_others_null (case);
2683
2684
2685
File: adacontrol_ug.info, Node: Examples of using AdaControl for common programming rules, Prev: Rules Usage, Up: Top
2686
2687
5 Examples of using AdaControl for common programming rules
2688
***********************************************************
2689
2690
In most projects, there are programming rules that define the way a
2691
program should be written. AdaControl performs checks, i.e. it finds
2692
occurrences of certain kinds of constructs. In this chapter, we give
2693
examples of commonly found programming rules, and how the corresponding
2694
checks can be written.
2695
2696
5.1 Automatically checkable rules
2697
=================================
2698
2699
Below are examples of rules that can be directly checked by AdaControl.
2700
2701
2702
Goto statement shall not be used
2703
check statements (goto);
2704
2705
2706
All type names must start with "T_"
2707
check naming_convention (type, "^T_");
2708
2709
2710
All program units must repeat their name after the "end"
2711
check no_closing_name;
2712
2713
2714
Pragma Suppress is not allowed
2715
check pragmas (suppress);
2716
2717
2718
Ada tasking must not be used
2719
check declarations (task);
2720
2721
2722
"=" and "/=" shall not be used between real types
2723
check real_operators;
2724
2725
2726
All tasks must provide an exception handler that calls "Failure" in the
2727
case of an unhandled exception
2728
check exception_propagation (task);
2729
check silent_exceptions (failure);
2730
2731
2732
Unchecked_Conversion shall not be used
2733
check entities (ada.unchecked_conversion);
2734
2735
2736
No global variable shall be declared in the visible part of a package
2737
specification
2738
check specification_objects (not constant);
2739
2740
2741
Predefined numeric types of the language shall not be used
2742
check entities (standard.Integer,
2743
standard.short_integer,
2744
standard.long_integer,
2745
standard.Float,
2746
standard.short_float,
2747
standard.long_float);
2748
2749
2750
Access to subprograms shall not be used
2751
check declarations (access_to_sp);
2752
2753
2754
Abort statements shall not be used
2755
check statements (abort);
2756
2757
2758
There shall be only one instantiation of
2759
Ada.Numerics.Generic_Elementary_Functions for each floating point type
2760
-- Put a --##RULE LINE OFF GEF
2761
-- for the one which is allowed
2762
GEF: check Instantiations (Ada.Numerics.Generic_Elementary_Functions);
2763
2764
2765
A local item shall not hide an outer one with the same name
2766
check Local_Hiding;
2767
2768
2769
There shall be no IOs in exception handlers
2770
check entity_inside_exception (ada.Text_IO.put, ada.Text_IO.put_line,
2771
ada.Text_IO.get, ada.Text_IO.get_line);
2772
Note that this checks for all overloaded procedures, but only those
2773
dealing with characters and strings (those defined directly within
2774
Ada.Text_IO). If the names "get" and "put" are not used for anything
2775
else than IOs, a more general form can be given as:
2776
check entity_inside_exception (all get, all put,
2777
all get_line, all put_line);
2778
This will check that no entity with the corresponding names appear in
2779
exception handlers.
2780
2781
2782
No procedure exported to C shall propagate exceptions
2783
check exception_propagation (interface, C);
2784
2785
2786
There shall be no Unchecked_Conversion to or from Address
2787
check instantiations (ada.unchecked_conversion, system.address);
2788
check instantiations (ada.unchecked_conversion, <>, system.address);
2789
2790
2791
There shall be no use clause except for Text_IO
2792
check use_clauses(ada.text_IO);
2793
2794
5.2 Rules that need manual inspection
2795
=====================================
2796
2797
Below are examples of rules that require manual inspection, but where
2798
AdaControl can be used to identify suspicious areas.
2799
2800
2801
All usages of the 'ADDRESS attribute shall be justified and documented
2802
search entities (all 'address);
2803
2804
2805
Specifying an address for a variable shall be restricted to hardware
2806
interfacing
2807
search representation_clauses(address);
2808
2809
2810
There shall be no memory leakage
2811
search Allocators;
2812
This rule identifies all allocations, and thus can be used to check
2813
that all allocated elements are properly deallocated.
2814
2815
2816
2817
Tag Table:
2818
Node: Top87
2819
Node: Introduction1999
2820
Node: Installation3575
2821
Node: Prerequisites4427
2822
Node: Building AdaControl5707
2823
Node: Customizing AdaControl7493
2824
Node: Integrating AdaControl into GPS9162
2825
Node: Program Usage10030
2826
Node: Running AdaControl10376
2827
Node: Rules syntax11468
2828
Node: Types and report messages13251
2829
Node: Parameters15218
2830
Node: Specifying an Ada entity name16057
2831
Node: Multiple rules23326
2832
Node: Commands24286
2833
Node: Go command24849
2834
Node: Quit command25478
2835
Node: Message command25826
2836
Node: Help command26289
2837
Node: Clear command26734
2838
Node: Set command27404
2839
Node: Source command28686
2840
Node: Inhibit command29464
2841
Node: Example of commands30291
2842
Node: Command line options and parameters30995
2843
Node: Getting help32247
2844
Node: Input units32979
2845
Node: Specifying rules36515
2846
Node: Output file38296
2847
Node: Interactive mode39205
2848
Node: Local deactivation ignoring40449
2849
Node: Verbose and debug mode40836
2850
Node: Treat warnings as errors41564
2851
Node: Exit on error41987
2852
Node: Project files42534
2853
Node: ASIS options43813
2854
Node: Return codes44878
2855
Node: Disabling rules45577
2856
Node: Helpful utilities47168
2857
Node: pfni47461
2858
Node: Adactl -D49259
2859
Node: Optimizing AdaControl49900
2860
Node: Tree files and the ASIS context51458
2861
Node: Choosing an appropriate combination of options53576
2862
Node: In case of trouble55907
2863
Node: Rules Usage57518
2864
Node: Allocators58835
2865
Node: Declarations59571
2866
Node: Default_Parameter60380
2867
Node: Entities61846
2868
Node: Entity_Inside_Exception63077
2869
Node: Exception_Propagation63565
2870
Node: Instantiations67800
2871
Node: Local_Hiding70007
2872
Node: Local_Instantiation70540
2873
Node: Max_Nesting71173
2874
Node: Naming_Convention71984
2875
Node: No_Closing_Name80690
2876
Node: Not_Elaboration_Calls81877
2877
Node: Parameter_Aliasing82906
2878
Node: Pragmas85833
2879
Node: Real_Operators86347
2880
Node: Representation_Clauses86760
2881
Node: Side_Effect_Parameters88111
2882
Node: Silent_Exceptions89965
2883
Node: Simplifiable_Expressions91719
2884
Node: Specification_Objects92696
2885
Ref: limitation96739
2886
Node: Statements97397
2887
Node: Unnecessary_Use_Clause98382
2888
Node: Use_Clauses100962
2889
Node: When_Others_Null101665
2890
Node: Examples of using AdaControl for common programming rules102427
2891
2892
End Tag Table
Loggerhead is a web-based interface for Breezy
Version: 2.0.1