Classpath and Sourcepath

Classpath

The classpath setting in JSwat is passed to the debuggee VM when it is launched. The way in which JSwat handles the classpath is quite simple. When JSwat is started, it checks if the classpath session property (see Sessions) has been defined. If it is empty, then the value of the System property java.class.path is used as the classpath.

When JSwat launches a debuggee VM, it sets the classpath of the debuggee VM to the classpath session property. When JSwat is connecting to a remote debuggee VM then the classpath in JSwat becomes the classpath of the remote VM. This is only temporary during the active remote session. Thus you will probably see a different classpath value depending on whether a remote debugging session is active or not.

When using either the load command or the "Start VM" dialog, you may provide an alternate value for the classpath. You do this with the "-cp" Java VM option. This will overwrite the classpath session property.

See the help for the classpath JSwat command to learn how to view and set the classpath used by JSwat. An easier way to modify the classpath is through the "Set Classpath" menu item in the "Options" menu.

Overriding the classpath at startup: If you wish to override the classpath session property when starting JSwat, you have only one option: invoke the classpath command. JSwat allows invoking an arbitrary command at startup, so simply invoke JSwat like so:

% java com.bluemarsh.jswat.Main classpath <CLASSPATH>
 or
% java -jar jswat2.jar classpath <CLASSPATH>

You may want to run another command as well, such as launching a debuggee VM. See the commands help for how to invoke multiple commands at one time.

Sourcepath

The sourcepath in JSwat looks just like a classpath setting. It is used for finding source files when the classpath does not refer to the locations of source files. The sourcepath is simply another means of finding the source file for a class. If a sourcepath is not set, JSwat will use the classpath to find the source files.

The format of the sourcepath is the same as the classpath. That is, if your source code is in /java/source/stuff and your classes are in /java/classes/stuff and the name of your class is stuff.Test, then the sourcepath should be set to /java/source, just as the classpath is set to /java/classes. You may also add Zip or Jar files to your sourcepath, and JSwat will find the source files inside of the named archives. Just as with the directories, the paths of the files in the archives must match the fully-qualified names of the classes (e.g. "java/lang/String.java" for "java.lang.String").

The sourcepath can be set one of two ways in JSwat. First, it can be passed when launching JSwat using the -D argument to the JVM, like so:

% java -Djava.source.path=/usr/java/src -jar jswat.jar

This value will override any previous sourcepath setting in JSwat. This is unlike the classpath, which defaults to the setting in JSwat rather than the java.class.path property setting.

The second way to set the sourcepath is with the sourcepath command. This works just like the classpath command and takes a set of directory paths and Zip/Jar files as an argument. On Windows the directory paths are separated with ';' characters, while on Unix systems it is the ':' character. An easier way to modify the sourcepath is through the "Set Sourcepath" menu item in the "Options" menu.

How JSwat Finds Source Files

JSwat uses the classpath and sourcepath to locate source files. Source files are those that end with the "Default extension", set in the preferences dialog. This defaults to .java. An example is perhaps the easiest way to describe the process.

Take for instance the class java.lang.String. Assume the source file is called String.java and is located in the directory /usr/java/src/java/lang. Additionally, assume that the classpath is set to /usr/java/jre/lib/rt.jar. In this case, JSwat is not able to find the source file for java.lang.String since it has not been given the location of the source code.

This is why the sourcepath is useful. With the classpath set to /usr/java/jre/lib/rt.jar, JSwat only sees class files in that jar file. If we set the sourcepath to be /usr/java/src then JSwat will look for the file named /usr/java/src/java/lang/String.java -- the source file for the java.lang.String class.