Java debugger  

Graphical Java Debugger - JDebugTool


Home
Screenshots
Features
Download
Starting Out
How To
Purchase
FAQ
Testimonials
News
Contact
About
JDebugTool RSS feed
 

Getting Started Tutorial

The following is a detailed tutorial on how to get started using the JDebugTool® graphical Java™ debugger. The How To Debug provides additional instructions on how to debug various Java applications. This tutorial assumes that you are using MS Windows®. The instructions are analogous for other operating systems as well.

  1. 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_23/

  2. 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 How To #3 How do I launch JDebugTool as an external tool in Eclipse?

    For NetBeans users, see How To #4 How do I debug a NetBeans project in JDebugTool?

  3. 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_23/bin/javac" -g -sourcepath "c:/Users/Mike/myjavafiles" -d "c:/Users/Mike/myclassfiles" *.java

  4. 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

  5. Invoking JDebugTool: To invoke JDebugTool, type the following command (all on one line):

    "c:/Program Files/Java/jdk1.6.0_23/bin/java" -cp "c:/Users/Mike/jdebugtool/jdebugtool.jar; c:/Program Files/Java/jdk1.6.0_23/lib/tools.jar" com.debugtools.jdebugtool.Main

    Note well 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_23/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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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.

  11. Connecting: There are three different ways to connect JDebugTool to debug your target program: Run, Attach, or Listen, depending on your situation:

    1. 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.

    2. 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:

      1. 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. See How To #5 How to remotely debug a Java application?

        If you are debugging a mobile application:

        • See How To #1 How to debug a Google Android™ app?
        • See How To #2 How to debug a Java ME app?

        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 How To #6 How do I debug an Apache Tomcat Servlet?

      2. 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.

    3. Listening: Another option besides attaching, is for JDebugTool to listen for the target JVM to connect to JDebugTool.

      1. 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.

      2. Then invoke your target JVM with the corresponding debugging flags, so that the target JVM will then connect to an already listening JDebugTool. See How To #5 How to remotely debug a Java application?

    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.

  12. 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 PC - Show the current execution point.
    • Close Top File Close Top File - Close the top source file.
    • Step In Step In - Single step (into method calls).
    • Step Over Step Over - Single step (over method calls).
    • Step Out Step Out - Step out of the current method.
    • Resume All Resume All - Resume execution.
    • Suspend All Suspend All - Suspend execution.
    • Run to Cursor Run to Cursor - Resume execution until the blinking cursor in the source code.
    • Stack Up Stack Up - Move up the method call stack.
    • Stack Down Stack Down - Move down the method call stack.
    • Toggle Breakpoint Toggle Breakpoint - Set/Clear the breakpoint at the blinking cursor in the source code.
    • Inspect... Inspect... - Drill down into the object reference containing the blinking cursor in the source code in the current scope.
    • Find... Find... - Display the Find Dialog.
    • Go To Line... Go To Line... - Display the Go To Line Dialog.

    The upper left region of JDebugTool contains the following tabbed Panels:

    • Source Tree Source Tree - Displays your source code hierarchy (see Step 9. Mounting Source Paths above).
    • Classes Classes - Displays the classes that have been loaded into the JVM.
    • Locals Locals - Displays the local variables in the current scope.
    • This This - Displays the object fields in the current scope.
    • Threads Threads - Displays the current threads executing in the JVM.
    • Watch Panel 1 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 Breakpoints - Lists the currently set breakpoints (stop execution when a particular source code line is reached).
    • Exceptions Exceptions - Lists the exceptions to catch in the debugger (stop execution when selected Java exceptions are thrown).
    • Watchpoints Watchpoints - Lists the currently set watchpoints (stop execution when a selected object field is read or written).
    • Stack Stack - Displays the current method call stack.
    • Navigator Navigator - Displays the class (including inner classes) and corresponding methods hierarchy obtained by parsing the top displayed Java source file.
    • Watch Panel 2 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. Double click on an event, to display the event details.
    • Input/Output - Displays Standard Input and Output, if the target was invoked via Run.
    • 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 directly enable/disable a breakpoint, hold down the Ctrl key and click in the line number column of the source file, on the appropriate line (that already has a breakpoint set).
    • To create a breakpoint when a particular method is called, navigate to the method body in the source code. Click to place the blinking cursor anywhere on the same line as the method name in the method signature, and then select Set Method Breakpoint from the right-click pop-up menu.
    • 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.

  13. 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.

  14. 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.

  15. 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 and How To Debug.

  16. 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.

Thanks for trying out JDebugTool !

View the Screenshots or Download now.


©2001-2010. debugtools.com LLC. All rights reserved.     Terms of Use     Trademarks     Privacy Statement