Remote debugging is the act of debugging a remote application. The term remote generally means the application being debugged is on a separate machine, connected via a network. While this is true, it is also true that the debuggee can reside on the same machine as the debugger. As far as the debugger is concerned, it is still remote debugging whether the application is physically near or far.
Remote debugging can be advantageous over launched debugging for a number of reasons. The debuggee may require a particular environment that is hard to replicate on the debugging machine. In cases involving large applications with long startup times, remote debugging will avoid the typical slowness caused by an attached debugger. Whatever reason you choose, this page provides instruction on remote debugging.
To debug a program that is already running, you must have started that program using the following command line:
java -Xdebug -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n <class>
This will start the JPDA debugger back-end and run the given
class. The socket transport will be used and the back-end will act as
the server. This allows JSwat to connect to the debugger back-end by
using the attach
command (or the like-named menu item in
the "VM" menu). The debugger back-end will print a
four-digit number in the command shell where you invoked
java
. This is the socket port number that JSwat must
connect to.
Once you have started JSwat and the debuggee program is running,
you can type "attach <port>
" to attach
to the debugger back-end through the given port number. JSwat should
display "VM attached" when successful.
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.
JSwat supports the shared memory connector, when the system allows
it. This is generally only true for Windows systems. To use the
shared memory connector, start the debuggee using the command line
shown above, but replace the dt_socket
with
dt_shmem
. A shared memory name will be displayed in the
debuggee's console. Use that as the argument to the
attach
command.
To end the remote debugging session, invoke the close
command. This will close the connection with the debuggee VM and
leave it running. If you invoke the kill
command
instead, this will terminate the debuggee VM. Alternately, the
"VM" menu has two items that perform the same operations:
"Detach from debuggee" and "Terminate VM".
In addition to connecting to an already running remote VM, JSwat
can listen for connections from new VMs. This is done using the
listen
command. It takes an optional port number to
listen to, or uses a default as generated by the JPDA. While JSwat is
listening for a remote VM to connect, you may launch the remote
debuggee using something like the following:
% java -Xdebug -Djava.compiler=NONE \ -Xrunjdwp:transport=dt_socket,address=<port> <class>
For the <port>
value, substitute the value
returned from the listen
command. Enter the name of the
class you want to debug in place of the <class>
argument. Once the remote VM starts up, JSwat will activate a new
debugging session and will be ready for your input.
Remote debugging through the shared memory transport seems to be less stable than the socket transport. JSwat will hang upon disconnect from the debuggee when using the shared memory transport. The socket transport does not have this problem. This is true not only for JSwat, but for other JPDA-based debuggers as well.
When JSwat and/or the debuggee appear to freeze and become
unresponsive, the solution is simple: kill the debuggee process. On
Unix, this means kill -9
, while on Windows it will be
necessary to "End Process" the java.exe
running the debuggee. Once the debuggee process is terminated, JSwat
will return and indicate that the debuggee has disconnected.
Check out the thorough documentation available for the JPDA library. These docs come with the JDK documentation for JDK 1.3 and above. Be sure to read up on the JPDA connectors to learn all the options when remotely debugging.