JSwat README

What is it?

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.


Requirements

J2SE

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.

JPDA

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.

Debugging Info

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.


Starting JSwat

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.

Passing Arguments

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:

Read the help section titled "Commands" to learn more about using JSwat commands.

Other Ways to Start JSwat

  1. As an alternative to using the Java Extensions Mechanism, you may invoke JSwat like so:
    java -Xbootclasspath/a:<JAVA_HOME>\lib\tools.jar -jar <JSWAT_HOME>\jswat.jar
    
  2. For a shorter invocation, list the aforementioned tools.jar file and the JSwat jar files in your classpath and invoke the program with this simple command:
    java com.bluemarsh.jswat.Main
    
  3. Another short invocation can be accomplished by copying the 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.


Documentation

The JSwat documentation is found in the docs directory. Additionally, there are several "how to" documents and a tutorial on the web site.


Stopping JSwat

Do not use Ctrl-C to exit!

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

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.


Getting the latest source

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.


Platform Particulars

Below are notes concerning particular platforms and what must be done to make JSwat work correctly on them.

Mac OS X

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.

Windows

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.

Windows NT and JDK 1.4

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