jEdit JSwat Plugin README


Acknowledgments

JSwat is a Java debugger developed primarily by Nathan Fiedler and can be found at the JSwat website. The jEdit plugin was initially developed by David Taylor, then later maintained by Stefano Maestri. In February of 2003 the plugin was merged into the JSwat project and Nathan Fiedler is now the maintainer of the plugin.


Introduction

The JSwat plugin integrates JSwat with jEdit, making it possible to debug Java code directly within jEdit. While not all of the JSwat functionality is provided through the graphical interface, the most important features are available in the menu and dockable window.

The plugin provides menu items and toolbar buttons for controlling the debuggee (start, stop, suspend, resume) and setting breakpoints. It also displays the usual JSwat panels for displaying threads, local and field variables, the loaded classes, the call stack, and so on. In addition, the usual JSwat command interface is available to utilize all of JSwat's debugging commands.


Requirements

The requirements for the JSwat plugin include the same requirements as JSwat itself. That is, the JPDA classes must be made available to the plugin in order for it to start. If the JPDA classes are contained in the tools.jar file in the JDK lib directory, they will be loaded automatically. If not, then continue reading this section.

See the JSwat README.html for how to make the JPDA classes available to the plugin. In addition to the possibilities listed in that file, you can also copy the tools.jar file from the JDK lib directory to your .jedit/jars directory.


Installing the JSwat plugin

If you have used a version of the JSwatPlugin prior to 1.3, you will have to manually delete the jswat2.jar file from the jEdit jars directory. Otherwise you will get exceptions when trying to start the plugin.


Using the JSwat plugin

Setting the JSwat session parameters

The following parameters control how the debuggee is started, as well as specifying the all-important classpath and sourcepath values. These should be familiar as they are the same sort of options provided in JSwat itself.

Java Home
The directory in which a JDK is installed, such as "c:\jdk1.4.1"
Java Executable
The name of the JVM executable, such as "java". The path to the JVM executable is assumed to be {Java Home}/bin.
JVM Arguments
Any arguments to be passed to the debuggee JVM, such as "-classic". Do not add the "-classpath" parameter here, as it will be added by JSwat.
Class Name
The fully qualified name of the main class of the debuggee application, such as org.gjt.sp.jedit.Main.
Application Arguments
Any command line arguments to be passed to the application. These will become the String[] args parameter to the main method of the main class specified above.
Class Path
The class path to be used. Specify it as you would when using the command line.
Source Path
A list of directories to search for source files. This is specified the same way as the class path.
Start VM suspended
If checked, the debugger will not start the application until the debuggee is resumed.
Show options before starting
If checked, the debugger options will be displayed before each debugging session.

Setting breakpoints

To set a breakpoint, place the caret on the line you wish to set the breakpoint on and select the Add Breakpoint item from the JSwat plugin menu (or click on the corresponding toolbar button).

A red marker will appear in the gutter next to any lines with breakpoints set.

Only line breakpoints can be set using the JSwat plugin. However, method breakpoints can be set using the usual JSwat stop command, although the plugin will not be able to indicate the location of the breakpoint.

Removing breakpoints

To remove a breakpoint, place the caret on the line with the breakpoint you wish to remove and select the Remove Breakpoint menu item from the JSwat plugin menu.

Starting a debugging session

To start a debugging session, select the Start VM menu item from the JSwat plugin menu. This will start the JSwat debugger and set the session parameters to reflect the settings of the plugin options.

Run until line

This feature allows you to place a temporary breakpoint on the line where the caret is. The target will run until this line (or another breakpoint is triggered). Once the temporary breakpoint has been triggered, it will be automatically deleted.

Get variable value

The value of variables can be seen by allowing the mouse pointer to hover over a variable name in the source code. If the variable is in scope, it's value will be displayed as a tooltip.


Building the JSwat plugin

The JSwat plugin is built using Jakarta Ant and a build.xml file is provided for this purpose. The default Ant target will build a jar file suitable for use as a jEdit plugin. Be sure to create a build.properties file to set the build properties to suit your environment. You will need to copy the JSwat jar files to your .jedit/jars directory in order to run the plugin.


Reporting Problems

If you find any problems in JSwat or the plugin, or you have an idea for a feature request, please send an email to jswat-bugs@bluemarsh.com with as much information as you can provide (software versions, environment settings, the problem/feature description).


Revision History

1.4 - Not Yet Released

1.3 - March 9, 2003

1.2.1 (Stefano Maestri)

1.2.0 (Stefano Maestri)

1.1.6 (Stefano Maestri)

1.1.5 (David Taylor)

1.1.4 (David Taylor)

1.1.3 (David Taylor)

1.1.2 (David Taylor)

1.1.1 (David Taylor)

1.0.1 (David Taylor)