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)
- Fixed bug 898: NPE in
JEditSourceView.scrollToLine()
when the debugger hits
a breakpoint.
- Fixed bug: breakpoint indicators and variable tooltips were not
shown on the first jEdit view, only on subsequently opened views.
Generally, JSwatPlugin should now behave better when more than one
jEdit view is opened. (But you may still open only one JSwat
instance.)
- Fixed bug: the Ant build file (
build.xml
) had a
bug so that the plugin version number of the
JSwat.props
file inside the JSwatPlugin.jar archive
was not updated correctly when using "ant
dist
" after "ant release
".
- Fixed bug: memory hole when unloading and reloading the
JSwatPlugin (text area decorators were not removed from text
areas).
- Fixed bug: JSwatPlugin did not use the AWT event thread to open
files and perform scrolling, resulting in a couple of concurrency
issues.
- Fixed bug: the source distribution files
JSwatPlugin-src-{version}.tar.gz
and
JSwatPlugin-src-{version}.zip
, which are built by
"ant dist
", wrongly included the class
binaries. This made them twice as large as they need to be.
1.5.5 - November 14, 2004
- Fixed bug 895: breakpoint indicator was not showing in the
source code viewer.
- Fixed bug 896: toolbar buttons are now enabling and disabling
appropriately.
1.5.4 - April 29, 2004 (Dirk Moebius)
- New: Added action "Hotswap Class" to hotswap the
class surrounding the current cursor position.
- Fixed bug: changing the dock position of the JSwat panel
required a restart of jEdit.
- Fixed bug: jEdit would sometimes throw
IndexOutOfBoundsException if the buffer was shorter than the
current debug position.
- Fixed bug: Invoking a JSwatPlugin action before the JSwat panel
was docked for the first time threw a NullPointerException.
- If the user opens a second jEdit view, display a message in the
dock panel saying that only one instance of JSwatPlugin is
allowed.
- BeanShell scripts can now invoke JSwat commands by calling
com.bluemarsh.jswat.plugins.jedit.JSwatPlugin
.invokeJSwatCommand(View view, String command)
.
- Renamed action "Dock JSwat Plugin" to "Show
JSwat Plugin" (associated shortcuts remain the same).
1.5(.0-3) - February 16, 2004 (Dirk Moebius)
- New: Remote debugging (actions "Attach to remote VM"
and "Detach from remote VM").
- New: Now opens source files in source file archives. You can
now specify source file archives in the source path (ZIP or JAR
files). For this feature, the Archive plugin is required (version
0.3.3 or higher), otherwise you will get an error message when the
debugger tries to open such a file.
- Updated to work with JSwat 2.21. Now requires jEdit 4.1pre1 or
higher.
- Reworked options panel; the launch properties (Java home etc.)
have been moved to the "Start VM" action; new JSwat
options "Stop in main() when launching", "Raise
window upon debugging event" and "Shorten class
names"; the plugin now shares its settings with an installed
JSwat standalone application.
- Actions "Add Breakpoint" and "Remove
Breakpoint" in the JSwat plugin menu replaced by a single
action "Toggle Breakpoint". You might need to reassign
jEdit shortcuts.
- Breakpoints shown in the text area gutter are now displayed
with an appropriate color: red for resolved, blue for unresolved,
gray for disabled (same as in JSwat standalone).
- The current debugging line is now indicated with a red
highlight. In previous versions, the plugin used jEdit's
current line indicator for this. This was inappropriate, because
you could move the cursor somewhere else and you would lose your
debugging position.
- The JSwat plugin now may be docked into the bottom or top area.
In this case, the two split panes are displayed side-by-side.
- JSwat debugging log information is now dumped to a file
jswat.log in the user's home, instead of the activity log. This
is faster.
- Fixed bug: setting breakpoint after changing the current buffer
did not work. This appears to have fixed bug 735 as well.
- Fixed bug 738: moved initialization out of
start()
method so plugin will launch faster.
- Fixed bug: breakpoints in inner classes now work.
- Fixed bug: variable tooltip did not show null values.
- Fixed bug: help document README.html did not show up in jEdit
Help.
1.4 - November 10, 2003
- Fixed bug 737: breakpoint indicator now appears and disappears
immediately, rather than when the text area just happened to be
repainted.
- Fixed bug 773: VM start dialog ignored the Java home and
application parameters values.
1.3 - March 9, 2003
- Added "Help" menu item to the JSwat plugin menu, so
the JSwat help can now be accessed.
- Looks for the JPDA classes on startup and reports an error if
they are not found.
- Replaced the red colored toolbar buttons; they clashed with the
predominantly blue-colored buttons.
- Put the classes in a proper package
(com.bluemarsh.jswat.plugins.jedit), conforming with Java coding
standards.
- Now remembers the position of the split-pane divider.
- Installed plugin in the JSwat source tree under
plugins/jedit
. It is now part of the JSwat
project.
- Removed copious amounts of unnecessary, duplicate, and/or
defunct code, and filled in some missing pieces.
- Breakpoints panel said "junk" because it was not
initialized properly. This change also fixed the other problems
with the breakpoints panel.
- Removed debugging messages from output panel.
- Added edit popup menus to text areas and text fields.
- Removed dependence on CommonControls classes; use the class in
JSwat that provides specialized functionality.
- Added "New" button to toolbar to start debuggee.
- After switching buffer, adapter still used old class name for
setting breakpoints.
1.2.1 (Stefano Maestri)
- Porting to JSwat version 2.8 (requires JDK version 1.4 or
later).
- Solved a bug (error when the plugin was not docked).
1.2.0 (Stefano Maestri)
- Porting to JSwat version 2.4 (requires JDK version 1.4 or
later).
1.1.6 (Stefano Maestri)
1.1.5 (David Taylor)
- Now uses MiscUtilities.isToolsJarAvailable() to find
tools.jar.
- Has a "run until line" action/button that will add a
once-off breakpoint to the line the caret is on.
- Now tries to show a variable's value as a tooltip.
- The JSwat dockable can be opened and closed from the plugin
menu.
- The JSwat options dialog can be opened from the plugin
menu.
- Clears the JSwat messages area when a debugging session
begins.
- Uses the CommonControls PathBuilder component to allow complex
class and source paths to be constructed easily.
- Now handles attaching to running processes better (using the
JSwat attach command).
1.1.4 (David Taylor)
- The plugin works with version 1.4 of JSwat.
- Use jEdit's current line highlight feature to show current
line while debugging. The user's preference is respected when
the debugging session ends.
- The options window is centered in the jEdit view when it is
displayed before starting the debugger.
- The JSwat breakpoints panel is now available in the lower split
of the plugin's dockable window.
1.1.3 (David Taylor)
- Toolbar only appears when debugger is active, and it appears in
the debugger window rather than on the jEdit toolbar.
1.1.2 (David Taylor)
- Plugin now looks for tools.jar in java.home.
- Plugin now has its own toolbar that is displayed in the jEdit
toolbar area.
- Plugin no longer uses JSwat.preferences, so this file no longer
needs to be copied from the jar to user.home.
- Plugin cleans up unfinished debugging sessions.
1.1.1 (David Taylor)
- Plugin code is now completely separate from JSwat source.
- JSwat UI elements are now displayed in a dockable window rather
than a top level frame.
- Plugin only uses actions.xml, and no longer uses classes that
extend EditAction.
- Plugin recognizes when a buffer has been closed and will reopen
it if required.
1.0.1 (David Taylor)