-
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_18/
Your Source Code:
Your source code hierarchy may be rooted in a single directory or multiple directories of your choosing.
This tutorial will assume that your source code hierarchy is rooted in the
following single directory, for example:
c:/Users/Mike/myjavafiles/
Your compiled object code hierarchy may be rooted in a single directory or multiple directories of your choosing.
Your compiled object code may also be located in a single jar file or multiple
jar files of your choosing.
This tutorial will assume that your compiled object code hierarchy is rooted in the
following single directory, for example:
c:/Users/Mike/myclassfiles/
This tutorial will assume that your class containing your main() method is,
for example:
mypackage.MyMainClass
and thus your corresponding source file is
c:/Users/Mike/myjavafiles/mypackage/MyMainClass.java
and thus your corresponding compiled class file is
c:/Users/Mike/myclassfiles/mypackage/MyMainClass.class
For Eclipse users, see FAQ #35
How do I launch JDebugTool as an external tool in Eclipse?
For NetBeans users, see FAQ #36
How do I debug a NetBeans project in JDebugTool?
Compiling:
Your source code 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.
If JDebugTool does not stop at the main() breakpoint, or does not
display your local variables or method arguments, or you cannot successfully set/hit
breakpoints, then you need to compile your source code with the -g
option in order for the compiler to generate debugging information.
To compile, first change to the directory containing your source code:
cd "c:/Users/Mike/myjavafiles"
Then invoke the Java compiler as follows
(all on one line, notice the -g option):
"c:/Program Files/Java/jdk1.6.0_18/bin/javac" -g
-sourcepath "c:/Users/Mike/myjavafiles" -d
"c:/Users/Mike/myclassfiles" *.java
Downloading JDebugTool: Next you will need to download JDebugTool.
You may save the downloaded jar file jdebugtool.jar
in a directory of your choosing.
This tutorial also assumes that you have saved jdebugtool.jar as, for example:
c:/Users/Mike/jdebugtool/jdebugtool.jar
-
Invoking JDebugTool:
To invoke JDebugTool, type the following command (all on one line):
"c:/Program Files/Java/jdk1.6.0_18/bin/java" -cp
"c:/Users/Mike/jdebugtool/jdebugtool.jar;
c:/Program Files/Java/jdk1.6.0_18/lib/tools.jar"
com.debugtools.jdebugtool.Main
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_18/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.
An optional project name parameter may be specified as the last
command line parameter, in order for the debugger to open a specific project.
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 5.
Invoking JDebugTool above.
Look and Feel: The Look and Feel, the font size, and a hint for the maximum number of lines
in a tool tip, are customizable by selecting Global Settings... from the Edit menu.
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 for each independent
source tree hierarchy.
See FAQ #1 for more details.
Thus you would mount the following Source Path (see Step 2. Your Source Code above):
c:/Users/Mike/myjavafiles
JDebugTool can automatically detect and fix incorrectly mounted source paths.
In the Source Tree panel, under an incorrectly
mounted source path, click on a Java source file in order to display the file.
JDebugTool will then automatically unmount the incorrect source path, and then
automatically mount the corresponding correct source path, after prompting the
user.
Stepping Excludes: Your third action in the JDebugTool GUI will be to
specify your Stepping Excludes -- any third party software (that you do not have
the source code to) that you do not want the debugger to step into. Select
Excludes... from the Execution menu.
-
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 (see Step 2. Your Source Code above):
In the Class [including package names] containing main()
field enter:
mypackage.MyMainClass
In the CLASSPATH field enter:
c:/Users/Mike/myclassfiles
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).
If while trying to Run, Attach or Listen above, JDebugTool pops up a dialog
entitled JDebugTool Instructions, then you will need to exit JDebugTool and return to Step 5.
Invoking JDebugTool above.
Debugging: Once you have successfully connected to the target JVM
(see Step 11. above), you are ready to start debugging.
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 blinking cursor in the source
code.
Stack Up - Move up the method call stack.
Stack Down - Move down the method call stack.
Toggle Breakpoint - Set/Clear the breakpoint at the blinking cursor in
the source code.
Inspect... - Drill down into the object reference containing the blinking
cursor in the source code in the current scope.
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 9.
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 line number column
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.
- Hover the mouse over an object reference (including array and
string references) displayed in the GUI in the current scope, to display
a multi-line tool tip showing the contents of the object.
- To drill down to display the fields of an object reference displayed
in a table, double click on (id=nnn) in a table row. To drill down
into an object reference in the source code display in the current scope, click on the object
reference in the source code, then click on the Inspect... button in the
tool bar (or right-click and select Inspect...). The same procedures
apply to drilling down into array and string references.
-
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.
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.
-
Uninstall: If you would like to remove the files created by JDebugTool:
- Remove the jdebugtool.jar file that you downloaded and saved
in Step 4. above.
- Remove the JDebugTool Desktop Icon that you optionally created in Step 6. above.
- If you purchased a license for JDebugTool in Step 14. above, save a copy
of your License File in a safe place, before proceeding to the next step below.
- JDebugTool saves its settings (and your purchased License File) in the jdebugtool
directory in your user's home directory. Remove the jdebugtool directory
and its projects subdirectory.
