| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
|---|
| 2 | <html> |
|---|
| 3 | <head> |
|---|
| 4 | <title>J User's Guide - The Java Debugger</title> |
|---|
| 5 | <LINK REL="stylesheet" HREF="j.css" TYPE="text/css"> |
|---|
| 6 | </head> |
|---|
| 7 | <body> |
|---|
| 8 | <a href="contents.html">Top</a> |
|---|
| 9 | <hr> |
|---|
| 10 | <h1>The Java Debugger</h1> |
|---|
| 11 | <hr> |
|---|
| 12 | <p> |
|---|
| 13 | J includes a lightweight JPDA-based Java debugger whose main advantage is its |
|---|
| 14 | integration with j. If you need a more powerful debugger, consider |
|---|
| 15 | <a href="http://www.bluemarsh.com/java/jswat/index.html">JSwat</a>. |
|---|
| 16 | <p> |
|---|
| 17 | <b>Installation</b> |
|---|
| 18 | <p> |
|---|
| 19 | For the debugger to work, j must be able to load classes from tools.jar, which |
|---|
| 20 | is normally found in the lib directory of your JDK installation. The simplest |
|---|
| 21 | way to make this possible is to use a startup script that looks like this: |
|---|
| 22 | <pre> |
|---|
| 23 | java -Djava.ext.dirs=[path to dir containing tools.jar] -jar j.jar</pre> |
|---|
| 24 | <p> |
|---|
| 25 | There are several other ways to accomplish the same thing. I'll just mention |
|---|
| 26 | one more: |
|---|
| 27 | <pre> |
|---|
| 28 | java -classpath [path to tools.jar]:[path to j.jar] Main</pre> |
|---|
| 29 | (On Windows, the ':' should be a ';', of course.) |
|---|
| 30 | <p> |
|---|
| 31 | Currently this second approach is used when you build j from source and do |
|---|
| 32 | "make install" or "ant install". |
|---|
| 33 | <p> |
|---|
| 34 | <b>The startup dialog</b> |
|---|
| 35 | <p> |
|---|
| 36 | The command <a href="commands.html#jdb">jdb</a> (Alt X, "jdb") brings up the |
|---|
| 37 | debugger's statup dialog. |
|---|
| 38 | <p> |
|---|
| 39 | "Main class" is the fully qualified name of the main class of your |
|---|
| 40 | application. For example: |
|---|
| 41 | <pre> |
|---|
| 42 | org.armedbear.j.Editor</pre> |
|---|
| 43 | <p> |
|---|
| 44 | "Arguments for main class" should contain any command-line arguments to be |
|---|
| 45 | passed to the application. For example: |
|---|
| 46 | <pre> |
|---|
| 47 | --force-new-instance --no-session Lisp.java</pre> |
|---|
| 48 | <p> |
|---|
| 49 | The value you enter for "Class path" will be passed to the debuggee Java VM as |
|---|
| 50 | the "-classpath" option. Use the platform-specific path delimiter character |
|---|
| 51 | (':' for Unix, ';' for Windows). |
|---|
| 52 | <p> |
|---|
| 53 | "Java home" is the value of JAVA_HOME for the debuggee VM. The default is |
|---|
| 54 | usually acceptable, unless you have some particular axe to grind. |
|---|
| 55 | <p> |
|---|
| 56 | The "Java executable" is normally just "java". |
|---|
| 57 | <p> |
|---|
| 58 | "Arguments for Java executable" should contain any command-line arguments to be |
|---|
| 59 | passed to the debuggee VM (for example, "-server"). Usually no arguments are |
|---|
| 60 | required. |
|---|
| 61 | <p> |
|---|
| 62 | If the "Start suspended" checkbox is checked, the Java VM will initially be |
|---|
| 63 | suspended, and you will need to use the "c" command (or the "Continue" button) |
|---|
| 64 | to start it. |
|---|
| 65 | <p> |
|---|
| 66 | If the "Start suspended" checkbox is unchecked, the Java VM will start up |
|---|
| 67 | normally. In this case, if you don't have any breakpoints set, a breakpoint |
|---|
| 68 | will automatically be placed on the main() method of your application's main |
|---|
| 69 | class. |
|---|
| 70 | <p> |
|---|
| 71 | "Source path" should contain a list of the directories in which to look for the |
|---|
| 72 | Java source of the code being debugged. You should specify the root directory |
|---|
| 73 | of each package tree that you care about. Use the platform-specific path |
|---|
| 74 | delimiter character (':' for Unix, ';' for Windows). For example: |
|---|
| 75 | <pre> |
|---|
| 76 | /home/peter/j/src:/home/peter/sun/j2sdk1.4.1_02/src</pre> |
|---|
| 77 | <p> |
|---|
| 78 | All of the textfields in this dialog remember their most recent contents, and, |
|---|
| 79 | like most textfields in j, they have persistent history that can be navigated |
|---|
| 80 | with the up and down arrows (or Ctrl P and Ctrl N). |
|---|
| 81 | <p> |
|---|
| 82 | <b>Debugging</b> |
|---|
| 83 | <p> |
|---|
| 84 | When you finally click the startup dialog's "OK" button (or press Enter), the |
|---|
| 85 | debugger process will start. You'll get a transcript buffer in the lower half |
|---|
| 86 | of the current editor frame, and a modeless control dialog will appear as a |
|---|
| 87 | separate, always-on-top top-level window (if you resize it to taste and put it |
|---|
| 88 | somewhere convenient, j will try to remember where it belongs). |
|---|
| 89 | <p> |
|---|
| 90 | The transcript buffer is read-only. It receives stdout and stderr output from |
|---|
| 91 | the application, as well as debugger messages. If you print the value of a |
|---|
| 92 | variable, for example, the results will appear in the transcript buffer. |
|---|
| 93 | <p> |
|---|
| 94 | The control dialog has three panes, with tabs labelled "Stack", "Threads", and |
|---|
| 95 | "Breakpoints". |
|---|
| 96 | <p> |
|---|
| 97 | When the VM is suspended, clicking on one of the stack frames in the stack pane |
|---|
| 98 | will navigate to the corresponding location in an editor source window. |
|---|
| 99 | (Clicking on the topmost stack frame is a good way to get back to the current |
|---|
| 100 | location if you've ventured off into the weeds.) |
|---|
| 101 | <p> |
|---|
| 102 | When the VM is suspended, clicking on one of the threads in the threads pane |
|---|
| 103 | selects that thread and updates the stack pane with the selected thread's |
|---|
| 104 | current call stack (if available). |
|---|
| 105 | <p> |
|---|
| 106 | In the breakpoints pane, you can delete breakpoints by selecting them and |
|---|
| 107 | pressing the Delete key. Breakpoints may be labelled "(deferred)"; this means |
|---|
| 108 | that the VM has not yet resolved them. This is normal if the VM has not yet |
|---|
| 109 | loaded the class containing the breakpoint in question, but it might also mean |
|---|
| 110 | that the breakpoint is entirely bogus. |
|---|
| 111 | <p> |
|---|
| 112 | The buttons across the top of the control dialog do, for the most part, what |
|---|
| 113 | their labels suggest. |
|---|
| 114 | <p> |
|---|
| 115 | "Next" executes the current line of code, stepping over method calls. |
|---|
| 116 | <p> |
|---|
| 117 | "Step" executes the current line of code, stepping into any method calls it may |
|---|
| 118 | contain. |
|---|
| 119 | <p> |
|---|
| 120 | "Step Out" continues execution until just after the current method returns. |
|---|
| 121 | <p> |
|---|
| 122 | "Suspend" suspends execution of the application. |
|---|
| 123 | <p> |
|---|
| 124 | "Continue" resumes execution at the address where the program last stopped. |
|---|
| 125 | <p> |
|---|
| 126 | The "Command" textfield is used to enter debugger |
|---|
| 127 | <a href="jdbcommands.html">commands</a>. If you're debugging a console |
|---|
| 128 | application, you can use the "stdin" command in the "Command" textfield to send |
|---|
| 129 | input to stdin of your application. |
|---|
| 130 | </body> |
|---|
| 131 | </html> |
|---|
