JBCD Crash Course

<h1>JBCD Crash Course</h1>

<h2>What is JBCD</h2>

JBCD (the Java Bytecode Debugger) is an interactive debugger for Java
bytecode. It allows a programmer to step through bytecode one
statement at time. The tool is indended for people who are writing
programs to generate or modify bytecode. JBCD can be used with any
Java compiler.

<h2>Running a program</h2>

In this example, we will debug the Hello World program:

<pre>
  public class HelloWorld {
    public static void main (String args []) {
      System.out.println("Hello world");
    }
  } 
</pre>

The method compiles into this bytecode:

<pre>
  0:    getstatic		java.lang.System.out Ljava/io/PrintStream; (2)
  3:    ldc		"Hello world" (3)
  5:    invokevirtual	java.io.PrintStream.println (Ljava/lang/String;)V (4)
  8:    return
</pre>

Normally the program is started by executing

<pre>% java HelloWorld</pre>

You can debug your program with JBCD by invoking jbcd, and passing
your normal command line as a command line argument as in

<pre>% java jbcd HelloWorld</pre>

When JBCD starts up, it prints the first instruction of the program,
and waits for input:

<pre>
% java jbcd Hello
0:    getstatic		java.lang.System.out Ljava/io/PrintStream; (2)
jbcd> _
</pre>

<h2>Stepping through code</h2>

You can use the <code>step</code> command to step through bytecode one
statement at a time.  The current instruction is printed after each
step.  If a method is invoked, the debugger will step into that
method.  The <code>next</code> command that steps over method
invokations has not yet been implemented.

<p>Use the <code>cont</code> command to continue program execution to
the next breakpoint.

<pre>
% java jbcd Hello
0:    getstatic		java.lang.System.out Ljava/io/PrintStream; (2)
jbcd> step
3:    ldc		"Hello world" (3)
jbcd> step
5:    invokevirtual	java.io.PrintStream.println (Ljava/lang/String;)V (4)
jbcd> cont
Hello world
% _
</pre>

<h2>Seeing where you are</h2>

JBCD prints out each instruction as you step through code.  
If you would like to see more of the code in the current method, use
the <code>list</code> command.  This will print the 10 statements
around the current instruction.

<pre>
% java jbcd Hello
0:    getstatic		java.lang.System.out Ljava/io/PrintStream; (2)
jbcd> list
0:    getstatic		java.lang.System.out Ljava/io/PrintStream; (2)
3:    ldc		"Hello world" (3)
5:    invokevirtual	java.io.PrintStream.println (Ljava/lang/String;)V (4)
8:    return

jbcd> _
</pre>

<h2>Setting breakpoints</h2>

Breakpoints are set with "break aClass.aMethod(args):index" or "break
aMethod(args):index".  If no class name is given, the current class is
assumed.  The index is optional.  If omitted the breakpoint is placed
at the first instruction in the method.  You can see a list of active
breakpoints by executing <code>break</code> with no arguments.

<p>Breakpoints are cleared with the <code>clear</code> command.  With
no arguments, <code>clear</code> removes all breakpoints.  Clear can
also be given a list of integer arguments, cooresponding to the ids of
breakpoints to remove.  Breakpoint ids are printed when the
breakpoints are listed by <code>break</code>.

<pre>
% java jbcd Hello
0:    getstatic		java.lang.System.out Ljava/io/PrintStream; (2)
jbcd> break main(java.lang.String[]):5
jbcd> break
[0] Breakpoint: Hello.main(java.lang.String[]):5
jbcd> cont
5:    invokevirtual	java.io.PrintStream.println (Ljava/lang/String;)V (4)
jbcd> clear 0
jbcd> break
No breakpoints set
jbcd> _
</pre>