Difference between revisions of "DLTK Validators User Guide"

From Eclipsepedia

Jump to: navigation, search
 
(7 intermediate revisions by one user not shown)
Line 1: Line 1:
 +
[[Category:DLTK]]
 
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.
 
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 ==
== 1. 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.
 
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.
  
== 1.1. External Checker Tutorial ==
+
== 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:
 
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:
  
Line 24: Line 22:
 
[[Image:Tutorial3.JPG]]
 
[[Image:Tutorial3.JPG]]
  
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.
+
 
 +
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.
  
 
[[Image:VTutorial4.JPG‎ ]]
 
[[Image:VTutorial4.JPG‎ ]]
 +
  
 
5. Provide a path to your script in the '''Command to run checker field'''.
 
5. Provide a path to your script in the '''Command to run checker field'''.
Line 41: Line 41:
  
 
[[Image:VTutorial6.JPG‎ ]]
 
[[Image:VTutorial6.JPG‎ ]]
 +
  
 
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.
 
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.
  
 
[[Image:Tutorial7.JPG‎ ]]
 
[[Image:Tutorial7.JPG‎ ]]
 +
  
 
8. We have configured the input for DLTK Validators.
 
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:
 
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''
 
''Error: myfile.tcl: line 16 Something wrong here''
 +
  
 
In this line we have the following tokens:
 
In this line we have the following tokens:
  
''myfile.tcl''           name of file where error has been found
+
<table>
 
+
<tr>
''16''                   number of line where error is located
+
<td> ''myfile.tcl'' </td>
 
+
<td>-name of file where error has been found </td>
''Something wrong here'' message describing the error
+
</tr>
+
<tr>
 +
<td>''16''</td>
 +
<td>-number of line where error is located </td>
 +
</tr>
 +
<tr>
 +
<td>''Something wrong here''</td>
 +
<td>-message describing the error</td>
 +
</tr>
 +
</table>
  
 
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.
 
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.
  
 
+
<table>
%f
+
<tr>
file name
+
<td> ''%f'' </td>
%n
+
<td>-file name</td>
line number
+
</tr>
%m
+
<tr>
problem message
+
<td>''16''</td>
 +
<td>-number of line where error is located </td>
 +
</tr>
 +
<tr>
 +
<td> ''%m''</td>
 +
<td>-problem message</td>
 +
</tr>
 +
</table>
  
 
So let's write a rule that assigns "error" to the pattern in our example: Error: %f line %n %m
 
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
+
Now push '''Add Rule''' button and type your pattern into pattern '''Output rule''' column of '''Pattern rules''' table
  
 
[[Image:VTutorial8.JPG]]
 
[[Image:VTutorial8.JPG]]
  
  
 
+
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.
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.
+
  
 
[[Image:VTutorial9.JPG‎ ]]‎  
 
[[Image:VTutorial9.JPG‎ ]]‎  
 
 
  
  
 
9. Repeat the steps 7-8 to add all the patterns you want to match
 
9. Repeat the steps 7-8 to add all the patterns you want to match
  
11. Push Ok.
+
11. Push '''Ok'''.
 
+
  
 
10. Repeat the steps  3-9  to add and configure all the external scripts  you want to use.
 
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.
11. Return to Validators preferences page and select a checkboxes on those items which you want to run with the project build.
+
  
 
[[Image:VTutorial10.JPG]]
 
[[Image:VTutorial10.JPG]]
 
 
 
  
  
 
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.
 
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.
+
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.
  
[[Image:VTutorial11.JPG]]
+
[[Image:Ext checker console.JPG]]
  
 
It navigates to the line of the file where problem has been detected. The problem itself is marked by the typical Eclipse error marker:
 
It navigates to the line of the file where problem has been detected. The problem itself is marked by the typical Eclipse error marker:
Line 113: Line 124:
  
  
14. Open Problems view. You'll see the error displayed in a manner compiler/interpreter errors and warnings are shown.
+
14. Open '''Problems''' view. You'll see the error displayed in a manner compiler/interpreter errors and warnings are shown.
  
 
[[Image:VTutorial13.JPG‎]]
 
[[Image:VTutorial13.JPG‎]]
 
  
  
Line 123: Line 133:
 
Have fun!
 
Have fun!
  
 +
== Tcl Checker Tutorial ==
  
1.2. Tcl Checker Tutorial
 
 
You need to have DLTK Project created  in your workspace.
 
You need to have DLTK Project created  in your workspace.
  
1. Run Window  -> Preferences
+
1. Run '''Window''' -> '''Preferences'''
  
 
[[Image:ValidTutorial1.JPG]]
 
[[Image:ValidTutorial1.JPG]]
 +
  
 
2. From the tree view of Preferences page select DLTK -> Validators. In the Validators table select Tcl Checker and push Edit Button
 
2. From the tree view of Preferences page select DLTK -> Validators. In the Validators table select Tcl Checker and push Edit Button
Line 135: Line 146:
 
[[Image:Choose_checker.jpg‎]]
 
[[Image:Choose_checker.jpg‎]]
  
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.
+
 
 +
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.
  
 
[[Image:Tcl_opptions.jpg‎ ]]
 
[[Image:Tcl_opptions.jpg‎ ]]
  
  
4. Click Ok. Now Tcl Checker is integrated into your workbench.
+
4. Push '''Ok'''. Now Tcl Checker is integrated into your workbench.
  
2. Tasks
 
  
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 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'''
  
 +
[[Image:Console_edit.jpg]]
  
  
2. How to edit validators
+
== How to edit validators ==
  
1. From the menu bar select Window -> Preferences.
+
1. From the menu bar select '''Window -> Preferences'''.
  
2. From the tree view of Preferences page select DLTK -> Validators.
+
2. From the tree view of '''Preferences''' page select''' DLTK -> Validators'''.
  
3. From the Validators table select the validator and push Edit button
+
3. From the '''Validators''' table select the validator and push '''Edit''' button
  
 
4. Provide options for validator
 
4. Provide options for validator
  
5. Click Ok
+
5. Push '''Ok'''

Latest revision as of 09:28, 6 May 2008

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.

Contents

[edit] 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.

[edit] 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.

ValidTutorial1.JPG


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

ValidTutorial2.JPG


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

Tutorial3.JPG


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.

VTutorial4.JPG


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.

VTutorial5.JPG


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

VTutorial6.JPG


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.

Tutorial7.JPG


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

VTutorial8.JPG


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.

VTutorial9.JPG


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.

VTutorial10.JPG


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.

Ext checker console.JPG

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

VTutorial12.JPG


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

VTutorial13.JPG


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

Have fun!

[edit] Tcl Checker Tutorial

You need to have DLTK Project created in your workspace.

1. Run Window -> Preferences

ValidTutorial1.JPG


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

Choose checker.jpg


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.

Tcl opptions.jpg


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



[edit] 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

Console edit.jpg


[edit] 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