How to Debug…

Index


There are 2 ways to debug under Kawa. One is through Kawa's native debugger and the other way is through JDB wrapper. In order to debug with either method it is necessary to create a Kawa project and compile all the files in the project with the compiler flag turned on. Please refer to compiler options for more details on this flag. If you do change this flag please issue a rebuild all command to rebuild all the files in the project.

Since all the JDK classes are not compiled with the debug flag it is necessary to either compile all the JDK classes with debug flag yourself or download the debug JDK classes from Kawa web site and copy it somewhere in your classpath so the debugger can find it. Without a debug JDK classes it is not possible to inspect the stack variables when the program is in JDK classes.

Please refer to JDB Debugger for more details on how to debug under Kawa using JDB.

Since Kawa native debugger uses the native calls to debug it is necessary to have the JDK/Bin path in your system PATH variable or to set the JDK/Bin path under Customize/Options/Directories so Kawa can find the appropriate JDK DLLs to load for the debugger. In case the DLLs are not found Kawa will display a message indicating that debugger cannot be enabled.

Breakpoint -

In order to set breakpoints under Kawa, open the source file and scroll to the class where you want to set the breakpoint and select Build/Breakpoint or its shortcut. This will add a new breakpoint at the cursor line and cursor class or remove the breakpoint if one already exists at the same line. JDB Debugger does not recognize the inner classes for setting breakpoint where as the Kawa native debugger will accept both local classes and inner classes for the breakpoint. Selecting Project/Breakpoint list will display all the breakpoints currently defined in the project.

Debugger UI is consistent with the rest of the Kawa UI. Kawa runs the same class or HTML file as Build/Run option during debugging. Please refer to how to run an app or applet for more details on how Kawa determines which class or file to run.

Select Build/Debug to start the debugger. When the debugger hits a breakpoint, Kawa automatically switches the project tab to debugger tab and displays all the thread information and current stack information as shown below -

A green arrow in the left margin of the editor always indicates the current line of execution. In the above figure the breakpoint and the current line happens to be on the same line. The debug tree displays all the different thread groups, which can be further expanded to check all the threads under each group. Each thread in turn can be expanded to display all the stacks under the thread.

The debug tree always automatically adds the breakthread as the last item of the tree and auto expands the breakthread to display all the stack information as shown in the figure above. Each stack can be expanded to display all the variables on that stack. Again, the debug tree adds the current stack as the last child of breakthread item and auto expands to display the current object and any local variables.

The object value displayed is the return value of toString call on the object. Expanding an object displays all the member variables of that object along with their value as shown in the figure below -

The variables are arranged alphabetically with all the static variables in bold and at the top of the tree followed by non-static variables. Static Final variables can be toggled on/off by right clicking on an object and selecting Static Final menu option.

Watch Variable -

Setting a watch on variable is as easy as expanding an object in the current stack. Like in the above figure the 'this' object has been expanded and this will automatically put a watch on that variable. In the figure below the parent object is expanded under this object and this will automatically put a watch on parent variable.

Since it is so easy to set a watch on a variable it is important to understand that every watch delays the debugger step, step over etc. as the debugger has to update the variables values for all watch variables. Therefore it is important not to expand objects unless you want to really monitor the variable as the step and step over will slow down considerably with more objects expanded or being watched.

Set Variable -

In order to set the value of a variable double click on the variable and this will display an appropriate dialog box to set the value of the variable. Currently, only simple data types - int, long, float, double, char, byte and Boolean can be set. Double clicking on the incRate variable displays the following dialog

Suspend and Resume Threads -

Threads can be suspended or resumed just by clicking right button on the thread and selecting the appropriate menu item. Suspended threads are drawn with bold font.

Step, Step Over and Step Up -

Once at a breakpoint you can either step, step over or step up. Step will execute one line of instruction, step over will step to the next line in the source skipping any method jumps in between and step up will execute the entire method and return back to the caller. The caller is indicated by the stack hierarchy in the debug tree.

Finding Package source files -

The current line of execution is updated in the editor with a green arrow in the left margin of the editor as shown in the top most figure. Double clicking on a variable in the editor will automatically locate the variable if found within the 'this' object and expand the 'this' object if necessary. In order for Kawa to find the source files properly it is important to add the class to the package tree. Kawa is shipped with all the JDK classes and there is no need to add these classes. However, any custom classes need to be added to the package hierarchy either as a class file or as a jar or zip file. Please refer to how to add classes to package hierarchy for more details on this.

Is it not enough if you just add the class to the package hierarchy as the source file may be in a different place than the class file. In order for Kawa to find the source file for a given class file in the package hierarchy it is important to set the package source path under Customize/Options/Directories properly.

Kawa uses the information from the class and the package source path to locate the source file and indicate the break line or line of execution.

Temporary Breakpoint -

It is possible to set temporary breakpoints when the debugger is at a breakpoint by right clicking on any line in the editor and selecting Break At Cursor line option from the context menu. This will set a temporary breakpoint at the cursor line and execute the debugger until that line.

Tooltip Display -

Holding the cursor for a fraction of a second on a variable in the editor will display a tooltip value for the variable. In the below figure the tooltip value for the MouseEvent argument e is displayed. The value displayed for tooltip display is the return value of toString calls. The value is displayed only if the variable is found in the breakthread current stack. The program searches the entire 'this' object under each stack in the break thread to find the variable. The search begins with the current this object and if not found it extends to other stacks in the break thread.

Finally all the output messages including program System.out messages are displayed in the Kawa output window just like during the program execution.

The debugger can be stopped anytime by selecting Debug/Exit or the appropriate toolbar button or the shortcut.