TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Ada Code Rule Checker

In a team program development, code rules are often used to ensure that programs being developed conform with a `standard' programming style. This makes the collectively developed program more readable and less error-prone. As a result, the cost of development and maintenance is reduced.

The following topics are covered in this chapter:


Code Rule Checker Displays

When the code rule checker executes, it examines the unit(s) for any code rule violations. If a unit violates any of the code rules, the violation(s) are highlighted in the source file. Choose Help > Explain in the editor window and click on the highlighted area for more details on the violations.

If multiple units have violations, a summary window listing all the units with violation is displayed. Use the Visit button in the Summary window on a unit name to display the editor window of the corresponding unit with all its violations highlighted.


Code Rule Syntax

In Apex, a code rule is represented as a triplet: a name, a switch attribute, and actual code for checking the rule.

A rule name is a string much like an Ada identifier containing alphanumeric characters and underscores (\Q_').

The switch attribute of a code rule can be one of the three states:

Uni_State
rule is either On or Off and has no other associated value (e.g., Use_Clause_In_Use)
Bi_State
rule is either On or Off and also has an associated boolean value
Nary_State
rule is either On or Off and also has an associated integer value (e.g., Maximum_Loop_Nests)

The Rational Apex code rule checker uses the code rules in the file Policy/Code_Rules.sw in the source view to determine which code rules to check, and the severity level at which a violation of a code rule will be reported. Each source view can have its own code rule set, so this file can be different from one view to another.

The code rules file is available from the Compile > Show > Code Rules menu item.


Predefined Code Rules

In Rational Apex, there are predefined code rules for the code rule checker. The code rules can be turned "On" (checked) or "Off" (not checked), severity levels can be set for the rules, and switches with associated boolean or integer values can have those values set by the user. The code rule checker employs the settings and does the checking accordingly.

The format of the Policy/Code_Rules.sw is lines of the form:

where

Value
is "On" or "Off" for Uni_State rules.
Value
is "Off", "True", or "False" for Bi_State rules.
Value
is "Off", or a number for Nary_State rules.
Severity
is "Error", "Warning", or "Informational". [Default: Warning]

Comments are introduced by "#" and continue to the end of the line.

The following is a list of the current rule names and what they check for:


Interface to the Code Rule Checker

You can display the defined code rules or check files against the defined code rules using either the command line interface or the Apex GUI.

Command-Line Interface

To check files against the defined code rules use the apex verify command.

GUI Interface

From the Apex GUI, the commands Compile > Check Rules and Compile > Show Code Rules provide access to the code rule checker. Compile > Show Code Rules simply displays the code rules in effect for the selected object(s). Compile > Check Rules checks the current selection against the predefined code rules. When this command is selected, the Check Code Rules dialog box is displayed.


Customizing the Code Rule Checker

The code rule checker is customizable and can be modified to meet the special code rule checking requirements of a development team. There are two ways to change what code rules are checked and how they are reported.

1 . Turn some of the predefined code rules "Off" or change their reported severity level.

2 . Create a new code rule checker executable and define new code rules to augment the predefined rules.

For Apex's predefined code rules, the individual rule checks can be turned "Off", or, their reported severity level can be changed. All of the predefined code rules default to "On" with a severity level of "Warning".

The list of code rules in effect for any given Apex view can be found in that view's Policy/Code_Rules.sw file. Individual rules may be "On" in one view and "Off" in another. They can also be reported at different severity levels in different views.

New code rules incorporated into a new code rule checker executable are controlled in the same way that the predefined code rules are controlled. Each new rule check defaults to "On" with a severity level of "Warning".

The Policy/Code_Rules.sw file for a view can turn individual rule checks to "On" or "Off" (or "True", "False", or a number) and can also specify a reported severity level of "Error", "Warning", or "Informational" for violations of individual rule checks.

To create a new code rule checker, use the following packages provided by Rational in $APEX_BASE/ada/code_rule_checker.ss/*.rel:

A customized code rule checker has two major components:

To create a specialized \Qchecker engine', the Code_Rules_Generic must be instantiated with appropriate values for these parameters:

The Code_Rules_Generic provides the routines Check_Unit and Check_Units. They are used to check a single unit or to check a list of units. They locate the unit (or the list of units) and then recursively visit every ASIS.Element in every unit and call the customer supplied Check_New_Rules procedure with each element. The elements are traversed using ASIS.Elements.Traverse_Element in a depth-first order. The procedure Check_New_Rules uses ASIS calls to retrieve necessary information about the element being visited, and to determine whether it violates the newly defined code rules.

When Check_New_Rules detects a rule violation, it invokes a

Checker_Messages.Emit routine to report the violation via the Apex environment. The report will appear in a Messages or Log window, or simply as output in a Shell window as appropriate depending on whether the checking was invoked from the GUI or from a shell command line.

Example Customization

The example customization units can be found in $APEX_BASE/ada/code_rule_checker.ss/*.rel.

The Example_New_Rules package, and the New_Check_Rules procedure, provide an example customization. Five new rules are added to the \Qchecker engine' to form the new customized code rule checker. The rule names are the lowercase string corresponding to their Ada enumeration literals, and their switch attributes are all Uni_State. The check code for the new rules is enclosed in the Example_New_Rules procedure. The main procedure New_Check_Rules collects the compilation unit filenames specified on the command line and then invokes either Check_Unit or Check_Units as appropriate to check the units.

The steps in customizing the code rule checker are:

1 . Copy the installed (and frozen) code_rule_checker.ss view associated with the version of Apex being used. This can be done with the File > Copy Object... dialog or it can be done from a shell command line using the apex copy_view command. The view to copy is probably the one named:

2 . Visit the new working view and start by using the New_Check_Rules procedure as the initial main program for the new customized code rule checker. It can be renamed if that is desired. This unit should require little or no modification.

3 . Edit the Example_New_Rules package specification. It is shipped with five example rules. As a first attempt it might be good to simply examine this unit and understand it. It can be renamed if that is desired. Once it is understood, the example rule names can be deleted and suitable names for the new customized rules can be substituted. It probably will not be necessary to edit this unit except to specify the enumerated names for the new rules. Feel free to have any number of new rules. There is an 80 character limit on the length of the rule names.

4 . Edit the Example_New_Rules package body. As shipped it specifies that every new code rule is a simple Uni_State rule (strictly "On"/"Off"). The Check_New_Rules routine will require modification. The code there that checked the example rules will need to be removed and code that checks the new customized rules will need to be substituted. There is a utility Error_Messages routine that will need to be modified to supply error messages appropriate for the new customized rules.

5 . Link the new code rule checker executable. If the name has not been changed, this is done simply by linking the New_Check_Rules procedure. The link step can be performed by the Files > Link dialog. The new code rule checker executable is now ready for use.

6 . Edit the Policy/Code_Rules.sw in the development team's source code views so that they include the new custom rule names. This provides per-view control over whether or not the new rules are used, not used, and how they are used.

7 . The simplest way to run the new code rule checker is from a shell command line. The command line consists of a series of Ada unit pathnames and/or Ada view pathnames. For example,

8 . The new code rule checker executable can be directly integrated into the Apex environment so that it can be used from the GUI. The environment varable $APEX_ADA_CRC is normally not set by Apex. However if a user sets $APEX_ADA_CRC so that it specifies the full path for a new code rule checker then that executable will be run instead of the default executable supplied by Rational.

One way to set $APEX_ADA_CRC is to set it before running apexinit to start a new Apex session. A better way is to change the site's (or the development team's) local customization directory so that the config.sh script sets $APEX_ADA_CRC.

The menu item Tools > Session > Environment... can be used to bring up a dialog that allows the user to set $APEX_ADA_CRC for the currently running session.

9 . The new code rule names implemented by the customized code rule checker can be added to the Policy/Code_Rules.sw files in the Ada model(s) being used by the development team. When new views are created they automatically inherit the Policy/Code_Rules.sw file of their model. If the model(s) being used are still the one(s) that were shipped with Rational Apex, the simplest approach is probably to copy the model(s) using the usual File > Copy Object... dialog followed by editing the Policy/Code_Rules.sw file of the new model view. The team can then switch over to using the new model. The file in the existing model can also be edited but those edits could be lost if the model was reinstalled or otherwise overlaid from installation media.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2004, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS