DLTK Validators User Guide

DLTK Validators Framework provides tools to run custom scripts on your source files and integrate these scripts into your workbench. Such scripts are commonly targeted to find and report problems in source files - so they are called "validators" or "checkers". DLTK Validators framework provides flexible yet simple way to manage checkers.

Getting Started

There are two types of checkers currently supported in DLTK Validators Framework: External Checker and ActiveState Tcl Checker. External checker allows you to integrate custom scripts. Tcl Checker - a batch mode code analyzer that uncovers errors in Tcl language scripts.

External Checker Tutorial

You need to have DLTK Project created in your workspace. If you want to integrate any number of custom checkers into your project, follow these steps:

1. From the menu bar select Window -> Preferences.

2. From the tree view of Preferences page select DLTK -> Validators. You'll see Validators page where you can add, remove and edit validators.

3. Push Add button. You'll see Add Validator dialog box. In the Validator Type drop down menu select External Checker.

4.Type name of the validator into Validator name text field. The name may be completely arbitrary - you will use names to distinguish between validators on your list.

5. Provide a path to your script in the Command to run checker field.

On Unix/Linux: Provide a path to any file that is marked as executable. on Windows: Provide a path to .bat file or .exe file.

You can use Browse... button to locate file on your hard drive.

6. Type arguments of your validation script into Checker arguments text field. You can use %f wildcard as a substitute for input file name.

7. Into Filename extensions text field type extensions of files on which the script must be performed. Separate extensions by commas. Use * if you want to run script on all the files.

8. We have configured the input for DLTK Validators.

Now let's configure the output. Validator is supposed generate error and/or warning reports. However to integrate these reports into workbench infrastructure DLTK validators Framework must be familiar with the format of such reports. So we provide interface for errors and warnings reports specification. Consider the following example of error report:

Error: myfile.tcl: line 16 Something wrong here

In this line we have the following tokens:

myfile.tcl	-name of file where error has been found
16	-number of line where error is located
Something wrong here	-message describing the error

We assume that above mentioned tokens: file name, line number and problem message are common for problem reports. So we provide set of predefined wildcards which you can use to define set of output rules.

%f	-file name
16	-number of line where error is located
%m	-problem message

So let's write a rule that assigns "error" to the pattern in our example: Error: %f line %n %m

Now push Add Rule button and type your pattern into pattern Output rule column of Pattern rules table

8. Select appropriate problem type from the drop down menu of the Type column. The default value is Error, but you can select Warning if you need to.

‎

9. Repeat the steps 7-8 to add all the patterns you want to match

11. Push Ok.

10. Repeat the steps 3-9 to add and configure all the external scripts you want to use.

11. Return to Validators preferences page and select a checkboxes on those items which you want to run with the project build.

12. Now external checkers are configured. Let's see what output you get and how it is integrated into your workbench infrastructure. Run project build.

13. Open Console view (if it is not opened by default). You 'll see an output of the checker. The line matched by the error pattern became hyperlink.

It navigates to the line of the file where problem has been detected. The problem itself is marked by the typical Eclipse error marker:

14. Open Problems view. You'll see the error displayed in a manner compiler/interpreter errors and warnings are shown.

The problem detected by your external script is now fully integrated into Eclipse workbench infrastructure.

Have fun!

Tcl Checker Tutorial

You need to have DLTK Project created in your workspace.

1. Run Window -> Preferences

2. From the tree view of Preferences page select DLTK -> Validators. In the Validators table select Tcl Checker and push Edit Button

3. In Edit Validator dialog box provide configuration options for Tcl Checker: correct path to Tcl Checker binary, Working mode and list of supressed problems.

4. Push Ok. Now Tcl Checker is integrated into your workbench.

How to run checkers without building a project.

1. Select source files in Package Explorer.

2. From the context menu select DLTK Validators -> Validate Selection With Console

How to edit validators

1. From the menu bar select Window -> Preferences.

2. From the tree view of Preferences page select DLTK -> Validators.

3. From the Validators table select the validator and push Edit button

4. Provide options for validator

5. Push Ok