Contents | Prev | Next
J2ME CDC 1.0
Porting Guide

Java Debugging with JDB

This document describes the procedure for using JDB with the CVM implementation.

Contents

Summary & Assumptions
Building & Running the JDWP Agent
Running JDB
What's in JDB
Other Sources of Information

Summary & Assumptions

JDB is a Java Debugger for debugging Java code. This document describes one method of running JDB with CVM on Linux. In order to run JDB with CVM, CVM must first be built with the build time option CVM_JVMDI=true. For the purpose of simplicity, the following discussions assumes that the CVM bundle is install in directory /cvm.


Building & Running the JDWP Agent

JDB communicates with CVM through the JDWP agent. The JDWP agent is dynamically linked into CVM to interface with the VM through the JVMDI interface.

To build the agent, cd to /cvm/ext/jpda/build/<platform>, and run 'make'. this builds the needed library in /cvm/jdk_build/<platform>/lib/<arch>, where <platform> is 'linux' or 'vxworks', and <arch> is 'i386' or 'PENTIUM'.

To run the JDWP agent with CVM on Linux, cd to /cvm/build/linux/bin and invoke

    cvm -Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000
        -Dsun.boot.library.path=../../../jdk_build/linux/lib/i386
        -Djava.class.path=your_class_path your_main_class

To run the JDWP agent with CVM on VxWorks, cd to /cvm/build/vxworks/bin and invoke

    runJavaJdp "-Djava.class.path=<your_class_path your_main_class>

runJavaJdb sets up the -Xdebug, -Xrunjdwp, -Dsun.boot.library.path arguments for you, and appends your classpath and main class before passing it to 'runJava'. The default setting for -Xrunjdwp is ':transport=dt_socket, server=y, address=8000' and the default setting for -Dsun.boot.library.path is '../../../jdk_build/vxworks/lib/PENTIUM. If you need to change either of these parameters, edit the file '/cvm/src/vxworks/biin/vxworks_java_md.c' and alter the runJavaJdb() function as necessary. Rebuild your cvm and VxWorks image and update your target.

On either platform, CVM should come up and hang. Don't worry. That is proper behavior because it is now waiting for the debugger front-end to connect before executing any Java byte codes.


Running JDB

Now that you have CVM up and running (if you don't, see Building & Running the JDWP Agent for CVM), you can start JDB and have it connect to your currently running instance of CVM. To do this:

  1. You will need JDK1.3 installed (typically in /usr/local/java/jdk1.3/linux/bin). If JDK1.3 is not installed, you can get it at http://java.sun.com/j2se/1.3. Of course, if your CVM is running on VxWorks, then your jdb will need to be running on a remote host that has JDK1.3 installed.
  2. In another terminal window (to keep the stdin/out for JDB separate from that of CVM), cd to the root directory where your Java source is stored. This is needed because JDB will look for the source in the directory from which it is invoked. If you don't do this, JDB will still run, but you won't be able to see the source code as you step through your debug cycle.

    Alternatively, you may choose to specify a source path from which JDB will load the source file of the classes being debugged. See the -sourcepath option below for information on how to do this. If you specify a source path, you won't have to cd to the root directory of your java source. JDB will search the specified source path fo the Java source files it is expecting.

    NOTE: It is the debugger front-end (JDB) that needs and sets the source path. The back-end (CVM) does not need the source path. However, if the back-end is running code that is not compiled from the source code that the front-end is refering to, you might get an erroneous correlation between code being executed in the back-end and the source you're viewing in the front-end. So make sure your source (.java file) and executable (.class file) being debugged are in sync.

  3. Next, invoke
        jdb -attach your_server_machine:8000 -sourcepath your_sourcepath
    
    • jdb is the java debugger that comes in the form of a Java app packaged with the JDK. If you have /usr/local/java/jdk1.3/linux/bin in your path, you should have no problem invoking it.
    • -attach your_server_machine:8000 tells JDB to connect to port 8000 on the specified server machine. Be sure to specify the same machine as the one where you are running the CVM back-end. If you're running on the same machine where CVM is running, you can choose to omit the your_server_machine: part. JDB will look on the local host for the specified port by default if you don't explicitly specify the server. If you specified a different port when you invoked CVM, then make sure to specify the same port number here.
    • -sourcepath your_sourcepath tells JDB where to look for the Java source files that correspond to the java class files being debugged. The sourcepath is analogous to the Java classpath except that it is for finding the .java files as opposed to the .class files. The sourcepath is structured as directory paths separated by colons.

For example, the following illustrates the invocation of JDB on a host machine named acorn to connect with a CVM instance running JDWP with the HelloWorld class (from the testclasses.zip that comes with CVM) on port 8000 of a server machine named peanut:

    acorn> jdb -attach peanut:8000 -sourcepath /cvm/src/share/javavm/test
Note: To find out about other JDB options, you can invoke jdb -help for a list of the supported JDB options. JDB will come up running (after a slight pause to load the JDK VM which it runs on). You should see the following:
    Initializing jdb...

    VM Started: No frames on the current call stack

    main[1] main[1]

Note: If you get here, all is well, you have set up the debugging session correctly. If not, go back and double check that you have entered everything correctly. Some possible reasons for JDB not working are:

Note: main[1] is a prompt where you can start entering JDB commands. Upon entering JDB for the first time, enter "list" to see a listing of the method you're currently in. You'll get a message like this:

    main[1] list
    No frames on the current call stack
    main[1]
This is because the VM has not entered any methods yet. To enter the very first method, type step and you will see a message like this:
    main[1] step
    main[1]
    Step completed: thread="main", HelloWorld.main(), line=14, bci=0
      14     if (args != null && args.length >= 1 && args[0].equals("-kgh")) {
    main[1]
The source code line displayed is the next line of code you will execute if you step the debugger (by typing step at the JDB command prompt).
Now, if you type list at the command prompt, you will see a partial listing of the source code like this:
    main[1] list
    10
    11         public class HelloWorld {
    12
    13             public static void main(String args[]) {
    14      =>      if (args != null && args.length >= 1 ** args[0].equals("-kgh")) {
    15                  System.out.println("Hullo from the E-spot VM!");
    16              } else {
    17                  System.out.println("Hello World.");
    18              }
    19             }
    main[1] 
You are now ready to try out a few other JDB commands and/or commence with your debugging activities.


What's in JDB

Now that you have JDB up and running, you can do usual debugger things with it. For example step, list the source, set breakpoints, etc. For example:

You can get a complete list of the available commands by typing help at the JDB command prompt.


Other Sources of Information

For more information on JDWP, and JVMDI, see the JavaTM Platform Debugger Architecture specification.


Contents | Prev | Next
Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jcp-cdc-comments@eng.sun.com
Sun