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 (attach, detach, 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 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.

To install the plugin, simply copy the jar files from the plugin directory to the jEdit jars directory. Then start jEdit and the JSwatPlugin should be available in the plugins menu.


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.

Class Path
The class path to be used when using the "Start VM" action. Specify it as you would when using the command line, or use the classpath builder by clicking on the associated button.
Note that this setting is ignored during remote debugging, because in this case the classpath of the remote debuggee gets used instead.
Source Path
A list of directories to search for source files. This is specified the same way as the class path.
Stop in main() method when launching
If selected, JSwat automatically sets a breakpoint at the first line of the main method of the main class. This applies only to a launched session (action "Start VM"), not a remote debugging session (action "Attach to remote VM").
Raise window upon debugging event
If selected, JSwat tries to raise the jEdit window above other windows on your desktop whenever a breakpoint is hit or some other debugging event occurred. Note that the behavior of this feature depends on the desktop manager you are using. For example, on newer Windows systems, this may cause the jEdit entry in the task bar to flash (in case it is not already in the foreground).
Shorten class names
If selected, JSwat will strip the package names from class names in the Locals, Breakpoints and Stack panel.

Setting/Removing/Disabling breakpoints

To set a breakpoint, place the caret on the line you wish to set the breakpoint on and select the Toggle Breakpoint action from the JSwat plugin menu.

A blue marker will appear in the gutter next to any lines with breakpoints set. If there is a VM session running, and the breakpoint class can be resolved, the marker will appear in red.

Note: 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.

If a breakpoint has already been set on the caret line, the breakpoint will be disabled. This is indicated by a gray marker.

If the breakpoint on the caret line has already been disabled, the breakpoint will be removed.

Starting a debugging session

To start a debugging session, use may either use remote debugging or launched debugging.
See "Launching a new debugging session" or "Attaching to a remote debugging session" below.

Launching a new debugging session

To launch a new debugging session, select the "Start VM" menu item from the JSwat plugin menu. A dialog will be shown with the following parameters:

Java Home
The directory in which a JDK is installed, such as "c:\jdk1.4.2"
JVM Executable
The name of the JVM executable, such as "java". The path to the JVM executable is assumed to be {Java Home}/bin.
Debuggee VM options
Any arguments to be passed to the debuggee VM, such as "-classic". Do not add the "-classpath" parameter here, as it will be added by JSwat, according to the classpath setting specified in the Global Options dialog.
Set -D Properties
This opens a dialog where you can specify the -D options passed to the debuggee VM.
Class name and arguments
This field must start with the fully qualified name of the main class of the debuggee application, such as org.gjt.sp.jedit.Main.
Append 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 at the line start.
Start VM suspended
If checked, the debugger will not start the application until the debuggee is resumed.

Attaching to a remote debugging session

To attach to re remote debugging session, select the "Attach to remove VM" menu item from the JSwat plugin menu. A dialog will be shown with the following parameters:

Transport Type
Choose the transport type that you have chosen to start the debuggee application with. JSwat supports socket transport and shared memory transport.
Note that JSwat supports the shared memory connector, when the system allows it. This is generally only true for Windows systems.
Host
When using socket transport, enter the hostname of the remote debuggee. If you leave this field blank, it defaults to "localhost".
Port number
When using socket transport, enter the port number of the remote debuggee listening for connection events.
Typically socket-based debugging means that each time the debugger is detached, the debuggee will listen on a new port. To avoid this, add "address=1234" to the list of arguments to the -Xrunjdwp option. The value is a port number between 1 and 65535. Usually port numbers below 1024 are for privileged use only. Be sure to choose a port number that is not being used by any other socket-based application.
Shared name
When using shared memory transport, enter the shared memory name of the remote debuggee here.

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, its value will be displayed as a tooltip.


Building the JSwat plugin

The JSwat plugin is built using Apache Ant and a build.xml file is provided for this purpose. You may want to create a build.properties file to set some of the build properties to suit your environment; in particular, you may want to set the install.dir property. See the plugin build.xml file for the details.

You will need to set your CLASSPATH to include the jEdit jar file (jedit.jar) so the plugin can find the classes it needs.

To build the plugin, invoke ant with no arguments. This will make the jar files and copy them to the install.dir directory. The jar files will need to be in the jEdit jars directory for jEdit to find 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.6 - February 4, 2005 (Dirk Moebius)

1.5.5 - November 14, 2004

1.5.4 - April 29, 2004 (Dirk Moebius)

1.5(.0-3) - February 16, 2004 (Dirk Moebius)

1.4 - November 10, 2003

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)