From the directory in which you want the checker stub files to be created, run kwcreatechecker with the following options:

kwcreatechecker --language java --type kast --code KASTJ.MYCHECKER

Result

A directory is created with the name you specified with --code . This directory contains the checker stub files. In the case of the example above, the directory is named KASTJ.MYCHECKER. The KASTJ.MYCHECKER directory contains:

• the checker configuration files (checkers.xml and help.xml)
• a test case sample (testcase.java)
• an Ant build file (build.xml)

The first test case for the checker should be as simple as possible. As the checker is developed more complex cases can be added and tested.

Example: Assignment instead of '+=' operator in an expression.

It's easy to mistype the '+=' operator in the expression 'a += 5' as an assignment operator: 'a =+ 5' ('=+' instead of '+='). This error still results in valid Java code.

Here is a very simple code fragment that will generate a Klocwork issue for this error:

class Testcase {
   public void method() {
      int x = 2;
      int j = x =+5; //Error: assignment instead of +=
   }
}

Add this code to the checker's test case file (KASTJ.MYCHECKER/Testcase.java).

Now that you have a simple test case, the next step is to open Checker Studio and paste your code snippet in to view the KAST node names, example code and help information. These will form the building blocks of your KAST expression, which will trace a path to the issue you are identifying with your checker.

1. Double-click the Checker Studio icon on your desktop, or at the command line, type:

   kwstudio
   

2. Paste your test case into the Source Code pane.

Browsing the tutorial test case

1. In the Source Code pane, click '=' in the expression 'x =+ 5'.

   Notice that the ExprBinary node for the second variable initializer statement is highlighted in the AST. For the example, this is the first node of interest in the KAST expression.

2. In the AST, expand ExprBinary.

   It has children Expr1 and Expr2 and the '@Op' attribute (shown in the Attributes table below the AST). This checker deals only with assignment expressions, so we should check the attribute's value, which should equal OP_ASSIGN.

3. The checker also deals with the second operand of the binary expression, so make a note of this and expand the Expr2 child.
4. Expr2 leads to the only node of type ExprPrefix. This means that ExprBinary contains an Expr2 of type ExprPrefix.
5. Click '+' in the source code. This highlights the ExprPrefix node in the AST. Note that this node has the '@Op' attribute. Our defect implies that this attribute should equal OP_PLUS.

The entities identified in the last step are: the ExprBinary and ExprPrefix nodes, Expr2 child, and two Op attributes (one should equal OP_ASSIGN, while the other should equal OP_PLUS).

Putting this together into the KAST expression gives:

//ExprBinary[@Op=OP_ASSIGN]/Expr2::ExprPrefix[@Op=OP_PLUS]

This KAST expression will search the AST for prefix plus expression that are left operands of assignments. When the above KAST expression is used, only '+5' will be highlighted.

If you want the issue to be reported on the assignment node (instead of the prefix plus expression), you should rewrite this pattern this way:

//ExprBinary[@Op=OP_ASSIGN][Expr2::ExprPrefix[@Op=OP_PLUS]]

In the second KAST expression, the whole assignment will be highlighted:(x=+5)

For more information about KAST expressions, see Java KAST syntax reference.

1. Type or paste the KAST expression into the Pattern pane in Checker Studio.

   The AST nodes matched by the expression are selected and the corresponding source code fragments are highlighted.

   

2. Adjust your KAST expression and test case as needed and re-test.

The next step in the KAST checker development process is to add more tests to the test case. Tests to add can be:

• false positive tests - ensure that the checker does not generate errors for certain conditions
• more complex tests - ensure that the checker will generate an error for special or more complex cases

For the sample checker in this tutorial, three more false-positive test cases will be added. The checks that will be added are:

• assignment operation without following '+' or '-'
• assignment followed by unary minus expression
• normal '+=' operation

These cases should not generate a Klocwork issue report.

Change the code in Testcase.java to:

class Testcase {
   public void method() {
      int x = 2; // OK - assignment only 
      int j = x =+ 5; // Error: assignment instead of '+=' 
      int k = x =- 100; // OK - unary '-' instead of unary '+' 
      x += 12; // OK - normal '+=' operation, no typo 
   }
}

Run the test again using Checker Studio. See Test the KAST expression.

The results indicate that no false positives were generated (all the test cases were covered).

Now that the checker's KAST expression is complete and tested, it can be added to the checkers.xml file, which was generated at the beginning of this tutorial.

1. Open KASTJ.MYCHECKER/checkers.xml in the editor of your choice.

   When the file was generated, its values were automatically populated with an error ID, severity, message, and title, as well as a sample KAST expression.

2. Look for the <pattern> tag.
3. Replace the sample KAST expression with your tested KAST expression, which is:

   //ExprBinary[@Op=OP_ASSIGN][Expr2::ExprPrefix[@Op=OP_PLUS]]

4. You can also edit the <error id> attributes, as required. For this tutorial, we'll change the title attribute to read "Assignment instead of plusequal" and the message attribute to read "Possible undesired assignment instead of plusequal operation".
5. Save the file.

Checker documentation can be added by editing the help.xml file.

The help file contents are bundled with the checker when you build the checker.

When deployed to a server project (and connected desktop), the help contents appear in the online help in Klocwork Static Code Analysis.

At minimum, you must provide a description for your checker.

See Example help.xml file for custom checkers.

Now that the checker's KAST expression is added to the checkers.xml file and help has been created, it's time to build the checker using Ant.

At the beginning of this tutorial, kwcreatechecker generated a build.xml file in the checker directory.

To build the checker library from the checker directory (KASTJ.MYCHECKER), run:

ant install

This generates a <CHECKER.CODE>.jar file, in this case, KASTJ.MYCHECKER.jar.

The checker now can be deployed to the Klocwork server, in which case it will be made available to all Klocwork connected desktops when they synchronize with the server. It can also be deployed to individual desktop installations.

To learn how, see:

• Server-project and connected desktop deployment
• Desktop-only deployment