JSwat is a graphical Java debugger front-end, written for the Java 2 platform, utilizing the Java Platform Debugger Architecture (JPDA). The source code is licensed under the GNU General Public License. This version of the program is maintained for compatibility with older Java 2 releases. You may want to consider upgrading to Java 2 version 1.4 or higher and use the latest version of JSwat.
JSwat requires the Java 2 Standard Edition software, version 1.2 or higher. Compatible software from other vendors may be used, if so desired. If you are running J2SE version 1.4 or higher, you should use the latest version of JSwat. It has many more features and is under constant development.
The Java Platform Debugger Architecture (JPDA) software, which
is included in most releases of the J2SE, is utilized by JSwat to
carry out its debugging activities. The required classes are
typically found in the <jdk>\lib\tools.jar file,
and begin with the prefix com.sun.jdi (where JDI
stands for Java Debug Interface). These classes may also be found
in a file called jpda.jar.
To find the JPDA classes, look in the lib directory
of the JDK installation. If there is a jpda.jar file
there, then you have the JPDA and you can skip all of these steps.
If, instead, there is a tools.jar file, there is a
chance that it contains the JPDA classes. Scan the output from
jar tf tools.jar and look for the
"com/sun/jdi" classes. If you see them, then
your tools.jar file contains the JPDA classes.
Otherwise you need to download the JPDA.
Linux JDK 1.2.2 users:
Yes, it seems that the JPDA is not included with the Linux JDK
version 1.2.2, despite what the web site may tell you. Download the
Sun SPARC version and extract just the jpda.jar file
and copy it to the lib directory of your JDK
installation. You will also need to follow the JPDA installation
instructions. The important step is to add
<jdk_home>/lib/i386 to your
LD_LIBRARY_PATH setting. If you fail to do this, you
will see the "can't find libjdwp.so" error message
when using JSwat.
JSwat, like most Java debuggers, requires that the classes to be
debugged be compiling using the -g flag. In addition,
do not compile the classes with the optimization flags, as that may
hinder debugging.
There are several ways to start JSwat, but we will only cover the simplest of these for now.
java -Djava.ext.dirs=<JAVA_HOME>\lib -jar
<JSWAT_HOME>\jswat.jar
Unix users must replace\with/in the line above.
Note that JAVA_HOME is the path to the JDK, while
JSWAT_HOME is the path to the jswat.jar
file. The <JAVA_HOME>\lib directory must contain
the tools.jar (or jpda.jar) file in order
for JSwat to start. This file contains the JPDA classes
(com.sun.jdi) used by JSwat. If the file containing
these classes is located elsewhere in your system, you must make
the appropriate change to the command used to invoke JSwat.
JSwat can accept a string of commands to be executed as soon as it has completed its startup. These commands are passed at the end of the command line used to start the program. Here are some examples:
java ... jswat.jar load -client MyClass arg1
arg2java ... jswat.jar attach mymachine:1234java ... jswat.jar "load MyClass; stop
MyClass:120; resume"Read the help section titled "Commands" to learn more about using JSwat commands.
java -Xbootclasspath/a:<JAVA_HOME>\lib\tools.jar -jar <JSWAT_HOME>\jswat.jar
tools.jar file and the JSwat jar files in your
classpath and invoke the program with this simple command:
java com.bluemarsh.jswat.Main
tools.jar file to the
<JAVA_HOME>\jre\lib\ext directory, then
starting JSwat like so:
java -jar <JSWAT_HOME>\jswat.jar
Note that the -jar option causes the classpath
setting to be ignored. This includes the path following the
-cp or -classpath options, as well as
the CLASSPATH environment variable.
The JSwat documentation is found in the docs
directory. Additionally, there are several "how to"
documents and a tutorial on the web site.
Using Ctrl-c to exit a program is generally incorrect. It is
especially incorrect with JSwat. You can expect things to break if
you do this. It must only be used in cases where the JVM
hosting JSwat has frozen. The correct way to exit JSwat is via
either the window close button, the exit command, or
the Exit item in the File menu.
Removing JSwat from your system is generally pretty simple. Find the files, wherever it is that you originally put them, and delete them. If, on the other hand, you used one of the packaged versions such as RPM or DEB, you will need to remove the package using the appropriate tool.
To remove all traces of JSwat from your system, you will need to
look in only one place. Find your home directory and remove the
.jswat directory found there.
The latest source code can be found in the Subversion repository
at http://www.bluemarsh.com/repos/jswat/1_x using any
web browser, or a Subversion client. See the
contributing
page on the JSwat web page for more information about using
Subversion to access the repository.
Below are notes concerning particular platforms and what must be done to make JSwat work correctly on them.
According to a Mac OS X 10.1.5 user, it is necessary to add the
hostname of your machine to the netinfo file.
Otherwise you will see an error about gethostbyname
when launching the debuggee. This is because the JPDA uses sockets
to communicate between JSwat and the debuggee, even when the
debuggee is launched by JSwat.
The JRE, often installed with the JDK, seems to cause more
problems than it solves. If JSwat tells you that the JPDA cannot be
found and you are certain you followed the instructions above
correctly, then chances are the JRE is getting in the way. I
recommend saving yourself time and trouble and removing the JRE
from your system. If you cannot do this, then at least delete or
rename the java.exe and javaw.exe files
in the Windows directory.
There seems to be a problem with using JDK 1.4 on Windows NT
4.0, relating to the DirectX features. The errors occur in the
method sun.awt.windows.Win32DDRenderer.doFillRectDD.
The solution appears to be quite simple, just add the following
option after java when starting JSwat:
-Dsun.java2d.noddraw=true