|
|
|
Getting Started Tutorial
The following is a tutorial on how to get started using the JDebugTool®
graphical Java™ debugger.
This tutorial assumes that you are using MS Windows®. The instructions are
analogous for other operating systems as well.
-
Installing Java:
The debugger requires that the
Java Software Developers Kit
JDK 1.5 (Java 5) or JDK 1.6 (Java 6) be installed, in order to run JDebugTool itself.
JDebugTool is built on top of the standard
JPDA (Java Platform Debugger Architecture),
which must be supported by your JVM (Java Virtual Machine) in order to use JDebugTool.
JDebugTool should be able to debug any JPDA compliant JVM --
debugging targets of JDK 1.3, JDK 1.4,
JDK 1.5 (Java 5), or JDK 1.6 (Java 6) are supported.
This tutorial will assume that you are using the JDK 1.6 (Java 6), but the instructions are
analogous for other versions as well. This tutorial also assumes that you have
installed JDK 1.6 (Java 6) in the following directory:
c:/Program Files/Java/jdk1.6.0_04/
Downloading JDebugTool: Next you will need to download JDebugTool.
This tutorial also assumes that you have saved jdebugtool.jar as:
c:/Users/Mike/jdebugtool/jdebugtool.jar
-
Invoking JDebugTool:
There are two ways to invoke JDebugTool (all on one line):
"c:/Program Files/Java/jdk1.6.0_04/bin/java" -jar
c:/Users/Mike/jdebugtool/jdebugtool.jar
Or the alternative way to invoke JDebugTool is as follows (all on one line):
"c:/Program Files/Java/jdk1.6.0_04/bin/java" -cp
"c:/Users/Mike/jdebugtool/jdebugtool.jar;
c:/Program Files/Java/jdk1.6.0_04/lib/tools.jar"
com.debugtools.jdebugtool.Main
The longer command line will avoid having to copy tools.jar in Step 4. below.
Note that there is no space after the semicolon. On UNIX® use a colon instead of
the semicolon as the classpath separator.
Notes:
Make sure you invoke the debugger by typing
"c:/Program Files/Java/jdk1.6.0_04/bin/java", not just typing
java. By default, your PATH is setup to use the JRE,
so you must override this by explicitly invoking the debugger with the full path
as given above to use the JDK (see FAQ #2).
An optional project name parameter may be specified as the last
command line parameter, in order for the debugger to open a specific project.
Copying tools.jar: The first time you invoke JDebugTool, you may get a message about
needing to manually copy the tools.jar file (into your JDK extensions directory).
JDebugTool will provide the instructions and will then exit. You will then need to
invoke JDebugTool for a second time, for the tools.jar to take effect.
Project Settings: First select Project Settings... from the Edit menu, to specify the Java compiler
used to compile your Project's source code, in order to hit breakpoints in inner classes correctly.
Mounting Source Paths: Your second action in the JDebugTool GUI will be to
Mount your Source Path(s). Select Mount Source Path... from the File menu for
each Source path. Note that you can mount multiple Source Paths.
See FAQ #1.
This tutorial will assume that your class containing your main() method is
mypackage.MyMainClass
and your corresponding source file is
c:/Users/Mike/myjavafiles/mypackage/MyMainClass.java
and your corresponding class file is
c:/Users/Mike/myclassfiles/mypackage/MyMainClass.class
Thus you would mount the following Source Path:
c:/Users/Mike/myjavafiles
-
Connecting: There are three different ways to connect JDebugTool to debug your target program:
Run, Attach, or Listen, depending on your situation:
-
Running: The easiest way to run (debug) your program in JDebugTool, is to select Run... from
JDebugTool's Target menu. In the resulting Run in Debugger dialog, enter the following
parameters:
Make sure that Breakpoint at main() is checked, in order for JDebugTool to stop
at the beginning of your main() method. Finally, click on the OK button.
-
Attaching: If your code does not contain a main() method, or you
need to debug your program remotely (executing on a different computer),
you will need to attach JDebugTool to an already executing target JVM
(Java Virtual Machine) that is executing your program to be debugged:
-
First you will need to invoke your target JVM with special debugging flags,
in order for JDebugTool to be able to later attach to your target JVM.
For the details, see JDebugTool's Context sensitive Help Viewer for many examples.
For the official documentation from Sun, see the JPDA Connection and Invocation Details
(FAQ #17).
If your code is contained within someone else's application, for example a
Servlet Container or Application Server, there should already be a way or
configuration, to start the application in debug mode, so that a Java debugger
can then attach to the application. Consult the application's documentation or start up
scripts for details. For example, see FAQ #25
How do I debug an Apache Tomcat 5.0 Servlet?
-
Then select Attach... from JDebugTool's Target menu. Then depending
on the debugging flags that were previously passed to the target JVM,
in the resulting Attach to Target dialog
select either the Shared Memory or the Socket tab, and enter the corresponding parameters.
Finally, click on the OK button.
-
Listening: Another option besides attaching, is for JDebugTool to
listen for the target JVM to connect to JDebugTool.
-
First JDebugTool must already be listening for a debugging connection.
Select Listen... from JDebugTool's Target menu.
In the resulting Listen for Target dialog,
select either the Shared Memory or Socket tab, and enter the corresponding parameter.
Finally, click on the OK button.
-
Then invoke your target JVM with the corresponding debugging flags,
so that the target JVM will then connect to an already listening JDebugTool.
For the details, see JDebugTool's Context sensitive Help Viewer for many examples.
For the official documentation from Sun, see the JPDA Connection and Invocation Details
(FAQ #17).
Debugging: Once you have successfully connected to the target JVM
(see Step 7. above), you are ready to start debugging.
Note that your program to be debugged must be compiled with the -g
option in order for the compiler to generate debugging information.
Do not compile with optimizations turned on and do not use an obfuscator.
Immediately above the Source code Window, is the JDebugTool Toolbar with the following buttons:
Show PC - Show the current execution point.
Close Top File - Close the top source file.
Step In - Single step (into method calls).
Step Over - Single step (over method calls).
Step Out - Step out of the current method.
Resume All - Resume execution.
Suspend All - Suspend execution.
Run to Cursor - Resume execution until the cursor.
Stack Up - Move up the method call stack.
Stack Down - Move down the method call stack.
Toggle Breakpoint - Set/Clear the breakpoint at the cursor.
Inspect... - Drill down into the highlighted variable in the source code.
Find... - Display the Find Dialog.
Go To Line... - Display the Go To Line Dialog.
The upper left region of JDebugTool contains the following tabbed Panels:
Source Tree - Displays your source code hierarchy (see Step 6.
Mounting Source Paths above).
Classes - Displays the classes that have been loaded into the JVM.
Locals - Displays the local variables in the current scope.
This - Displays the object fields in the current scope.
Threads - Displays the current threads executing in the JVM.
Watch Panel 1 - Displays the values of variables in the current
scope that you have selected to watch.
The lower left region of JDebugTool contains the following tabbed Panels:
Breakpoints - Lists the currently set breakpoints (stop execution
when a particular source code line is reached).
Exceptions - Lists the exceptions to catch in the debugger
(stop execution when selected Java exceptions are thrown).
Watchpoints - Lists the currently set watchpoints (stop execution
when a selected object field is read or written).
Stack - Displays the current method call stack.
Navigator - Displays the class (including inner classes) and corresponding
methods hierarchy obtained by parsing the top displayed Java source file.
Watch Panel 2 - Displays the values of variables in the current
scope that you have selected to watch.
The lower right region of JDebugTool contains the following tabbed Panels:
- Events - Displays debugging events as they happen.
- Input/Output - Displays Standard Input and Output.
- Expressions - Evaluates simple Java expressions (including method calls)
that you type.
Finally, here are some more debugging tips:
- To directly set a breakpoint, click in the left-hand
margin of the source file on the corresponding line number.
- To stop execution in the debugger, when a certain exception is thrown
in your program, select Catch... from the Exceptions menu.
- To drill down to display the fields of an object reference displayed
in a table, double click on (id=nnn) in a table row.
-
Ending: To end your debugging session, select Kill... from the
Target menu to terminate the target JVM.
If JDebugTool had connected to
the target JVM via attach or listen, then you can also select Detach...
(instead of Kill...) from the Target menu to detach JDebugTool from the target JVM, so that the
target JVM can continue executing.
To exit from JDebugTool, select Exit... from the File menu.
Desktop Icon: To obtain a JDebugTool desktop icon, select Desktop Icon...
from the Help menu. You can then manually create a desktop shortcut for launching
JDebugTool with the icon.
Note: to prevent a shell window from be launched when invoking JDebugTool
from a shortcut, substitute the command javaw instead of java in Step 3.
Invoking JDebugTool above.
License File: After you have evaluated JDebugTool, and have
purchased a License, select License Info...
from the Help menu, to see where to install the License File. If the
evaluation period has already expired, JDebugTool will display on start up,
where to install the License File.
More Help: More JDebugTool help, is available in the Help menu,
by right clicking and selecting Help... from the resulting popup menu,
by clicking on the Help button in popup dialogs, or
by pressing the F1 key. Also check out the JDebugTool
FAQ.
Thanks for trying out JDebugTool !
Subscribe to the JDebugTool RSS
News feed to receive notifications of new JDebugTool® releases.
|
