JavaTM Platform Debugger Architecture - Readme

JavaTM Platform Debugger Architecture (JPDA) is the new debugging support for the Java 2 Platform. JPDA provides all the infrastructure needed to build professional end-user debugger applications. Check the license agreement for redistribution information.

JPDA has been tested most on the Classic Virtual Machine platforms shipped with the Java 2 Software Development Kit (J2SDK), version 1.2.2, and it is known to work well on those platforms. However, JPDA can be used, with restrictions, on any of the following versions of Sun VMs. Click on the VM you use to learn more about the bugs and limitations associated with it.

We are very interested in your input. Send comments, questions, and bug reports to java-debugger@java.sun.com

The Debugging Interfaces

This release contains the reference implementations of the Java Debug Interface (JDI) and the Java Debug Wire Protocol (JDWP). See the documentation in doc/index.html for more information on these interfaces. We provide a set of class files and native libraries which implement the JDI. This implementation uses the JDWP to communicate between a debugger virtual machine (front-end) and target virtual machine (back-end). The front-end support is contained in a set of class files. The back-end support is contained in native libraries that are loaded into the target virtual machine when an application is debugged.

The Java Virtual Machine Debugging Interface (JVMDI) is a low level native interface that is provided by a Java virtual machine.

Contents

The doc directory contains overview documentation for the various interfaces as well as detailed documentation for the JDI in doc/jdi/index.html.

The lib directory contains jpda.jar: the JDI specification packages, the reference implementation of the JDI, and example debugger applications.

The examples directory contains examples.jar, source code for the example applications jdb and javadt.

On Win32 platforms, the bin directory contains

On Solaris platforms, the bin directory contains

On Solaris platforms, the lib/sparc directory contains

Manually Launching the Application VM

If you are running the version of jdb provided in this release, the application VM is launched for you with the debugger back end loaded. However, in the following cases, you will be launching your own application VM, either by hand or in your implementation.

  1. Remote debugging with the -attach or -listen jdb option.
  2. You are implementing a debugger which uses the JDWP directly.
  3. You are implementing a debugger back end which uses JVMDI.

Currently, the first two cases require a command line like the following:

java -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y -classpath class-path class-name

The -Xdebug option enables debugging. The -Xnoagent disables the default sun.tools.debug debug Agent. The -Djava.compiler=NONE disables the JIT compiler.

For the third case, you must use the same command line options as described above, but you are free to use your own mechanism for loading the JVMDI client into the application VM. You do not need to use -Xrun.

The Connection and Invocation Details document contains more information on necessary VM invocation options and sub-options of -Xrunjdwp.

Known Bugs and Limitations

All Platforms

The following bugs and limitation exist on all platforms.

Sun Win32 Production VM and Solaris Reference VM, 1.2.2

The following bugs exist in the 1.2.2 Win32 classic VM and Solaris Reference VM JVMDI implementations.

Sun Win32 Production VM and Solaris Reference VM, 1.2 and 1.2.1

In addition to the bugs listed above for version 1.2.2, the following bugs exist in the 1.2 and 1.2.1 Win32 classic VM and Solaris Reference VM JVMDI implementations.

Sun Win32 Production VM and Solaris Reference VM, earlier than 1.2

Releases of the Sun Classic VM earlier than 1.2 cannot be used with this release of JPDA.

Solaris Production VM, 1.2.1_03

Important: Due to a bug in this version of the Production VM, you should set the environment variable _JAVA_JDWP_OPTIONS to "stdalloc=y" before running with this version of the Solaris Production VM with JPDA. See list below for details.

JPDA has undergone limited testing with the 1.2.1_03 Solaris Production VM. It is presumed that all Solaris Reference VM, 1.2.1 bugs also exist in this VM. The following bugs are known to exist in this version of the Solaris Production VM JVMDI implementation.

Solaris Production VM, earlier than 1.2.1_03

Production releases of the Sun Solaris VM earlier than 1.2.1_03 cannot be used with this release of JPDA.

HotSpot Performance Engine 1.0 (Win32 and Solaris)

JPDA support is considered to be beta quality in version 1.0 of the Hotspot Performance Engine. The following bugs exist in this version of the HotSpot Performance Engine JVMDI implementation.

Change Log


Copyright © 1997-1999 Sun Microsystems, Inc. All Rights Reserved. 

Please send comments to: java-debugger@java.sun.com