\input texinfo     @c -*- mode: texinfo; mode:auto-fill -*-
@c %**start of header
@setfilename jdibug.info
@settitle JDIbug User Manual
@c %**end of header

@ifnottex
@node Top
@top JDIbug User Manual
@end ifnottex

@menu
* Rationale::          Why I created JDIbug
* Installation::       How to install JDIbug
* Configuration::      Configuring JDIbug
* Connecting::         Connecting to and Disconnecting from a debuggee
* Breakpoints::        Setting and clearing breakpoints
* Stepping::           Stepping into, over and out of source codes
* Locals Browser::     Using the Locals Browser
* Frames Browser::     Using the Frames Browser
* Breakpoints Buffer:: Using the Breakpoint Buffer
* Window Layout::      Changing the default window layout
* Bug Reporting::      When you think there's a bug in JDIbug
@end menu

@node Rationale
@chapter Rationale

One word, locals browser. As I started using JDE, there are two
debuggers that are available, which are jdb and jdebug.

jdb is too simple to be used as a debugger, I find myself doing
@code{locals} repeatedly while stepping through the codes, and the
output of @code{locals} are not sorted! Its worse when I want to
inspect the attributes of particular objects.

jdebug is too slow and buggy for my liking, stepping through the
source files takes forever.

I then started using jswat, which is very user friendly. But it
doesn't integrate with Emacs.

So I created JDIbug.

@node Installation
@chapter Installation

JDIbug is hosted at googlecode, at
@uref{http://code.google.com/p/jdibug/}

Download all the package file and untar them into somewhere within
your @code{load-path}. For example, I keep all my emacs modules under
my @file{~/emacs/site}, so the jdibug @file{.el} files will go into
@file{~/emacs/site/jdibug-0.1}.

Then add the path into your @code{load-path}, and @code{require} it,
for example, I have the following in my @file{.emacs} file:

@example
(add-to-list 'load-path (expand-file-name "~/emacs/site/jdibug-0.1"))
(require 'jdibug)
@end example

That's it, you are good to go.

@node Configuration
@chapter Configuration

Although JDIbug current does not rely on any data from JDE, a lot of
things are made very simple when using JDIbug with JDE. So please
install JDE if you have not yet done it.

There are only two parameters that you need to configure before you
can start using JDIbug, which is the @code{jdibug-connect-host}
parameter and the @code{jdibug-connect-port} parameter.

@code{jdibug-connect-host} specifies the hostname of the debuggee
process that you want to debug. And @code{jdibug-connect-port}
specifies the port to connect to.

If you have multiple projects set up using JDE's @file{prj.el} file,
you can set the two parameters inside the @file{prj.el} file so that
different projects can be connected using different host/ports by
JDIbug. Having said that, JDIbug currently @emph{does not} support
more than one debugging session per emacs session.

@node Connecting
@chapter Connecting
After configuring JDIbug, use the key sequence @kbd{C-c C-c C-c} in a
jde-mode buffer to connect to the debuggee process. By default, the
frame will be splitted into windows each displaying different
buffers. With the java source file on the top left, the locals browser
on the top right, the stack browser on the bottom left, and the
breakpoints list on the bottom right.

To disconnect from the debuggee, use the key sequence @kbd{C-c C-c
C-d}.

@node Breakpoints
@chapter Breakpoints
You can set breakpoints before or after you have made the connection
to the debuggee.

To toggle the breakpoint on the current line of java source, use the
key sequence @kbd{C-c C-c C-b} in the java source buffer. This toggles
the breakpoints on the current line between, disabled, enabled, and no
breakpoint. The ``disabled'' status is just an easy way of remembering
that line as a line of interest but you do not want the debugger to
stop there.

If the line of code is not loaded when the breakpoint is requested, it
will be marked as pending. When the class is finally loaded, the
breakpoint will be installed.

You can also break on all the methods a class by positioning the
cursor on the first line in the class (usually @code{^public class})
and calling @code{jdibug-toggle-breakpoint} or @kbd{C-c C-c
C-b}. Multiple breakpoints will be installed for the first line of
every method in the class. Note that the pseudo method @code{<init>}
will also be breakpoint-ed.

@node Stepping
@chapter Stepping
When the debugger is suspended, you can use the following key
sequences to step through the program.

@example
C-c C-c C-n to step over.  
C-c C-c C-i to step into.  
C-c C-c C-o to step out.
@end example

As these keys are used very often, I bind them to function keys for
faster access. I have the following in my .emacs file:

@example
(define-key jde-mode-map [f8]   'jdibug-step-over) 
(define-key jde-mode-map [M-f8] 'jdibug-step-into) 
(define-key jde-mode-map [f7]   'jdibug-step-out) 
(define-key jde-mode-map [M-f7] 'jdibug-resume)
@end example

When you are done, you can use the key sequence @kbd{C-c C-c C-r} to
resume the debugger process. Or if you have added the snipplet above,
you can just @kbd{M-f7} for that.

@node Locals Browser
@chapter Locals Browser
The locals browser uses the emacs tree-mode to display the local
variables. Each of the variables can be expanded to view the member
variables by clicking on the expand icon.

When the cursor is over any element in the tree, you can press the
@kbd{s} key to invoke the @code{toString} method on the variable under
the cursor. The result will be printed in the echo-area. You can also 
press the @kbd{c} key to print the class name of the object under the
cursor in the echo area.

One extra feature that is very useful in the Locals Browser is that it
reduces the number of clicks that you have to do to inspect a
variable. By default, a number of java objects will be displayed with
their string representation, for example Boolean, Number, StringBuffer
etc. For decendants of Collection and Map, there will be extra
information displayed about the number of items that are within the
Collection of Map.

If you like the above feature, there's more! You can define custom
displayer functions for your own java objects, for example, if you
have a class @code{com.foo.Dog} which have a getter called
@code{getName}, and you want to see the name of the dog displayed, you
can just add the following line into your @file{.emacs} (after the
@code{(require 'jdibug)} line) and viola, you will see the name of the
dog instead of the @code{Dog} class name. The method that is specified
must receive no arguments and returns a @code{java.lang.String}.

@example
(add-to-list 'jdi-value-custom-set-strings '("com.foo.Dog" "getName"))
@end example

When expanding a Collection or Map, the locals browser will be
displaying the contents as an array instead of having you to click one
or two more times to see the contents within the Collection or Map.

At the end of every object, there's a pseudo node named @code{methods}
that can be expanded to show all the methods for that object and also
static methods of the object's class. Expanding any of the methods
will invoke the method and the results of the invocation will be shown
in the expanded node. Currently only methods which does not need
arguments can be invoked.

@node Frames Browser
@chapter Frames Browser
The frames buffer is a simple list of all the frames from the
@code{main} up to the current function. It provides a simple
caller/callee stack of the current breakpoint. If the frame points to
a location which can be corresponded to a line of code in the source
path, the frame will be clickable, and the source code buffer will be
updated to show the file and line number. The locals browser will also
be updated to show the locals of that particular frame.

Please note that the current execution point does not change when you
switch between the frames, so if you do @code{jdibug-step-over}, the
stepping will go back to the original execution point.

@node Breakpoints Buffer
@chapter Breakpoints Buffer
The breakpoints buffer shows a list of the current active and disabled
breakpoints. Clicking on the breakpoints will show the line of code of
the breakpoint in the source code buffer.

@node Window Layout
@chapter Window Layout
The default four buffers layout is what I like the most on my
screen. If you don't like it, you just have to create your own
functions that create the window layout of your liking, and then add
this in your @file{.emacs} file:

@example
(remove-hook 'jdibug-connected-hook 'jdibug-debug-view) 
(remove-hook 'jdibug-detached-hook  'jdibug-undebug-view)
@end example

And then proceed to add your equivalent functions in the above
hooks. You can refer to the two functions @code{jdibug-debug-view} and
@code{jdibug-undebug-view} for a start.

@node Bug Reporting
@chapter Bug Reporting
If you think there's a bug in JDIbug, please submit the log together
with a description of what you have done.

JDIbug uses the @file{elog.el} module that I have written for this
purpose.

Run the following piece of code
@example
(elog-set-appenders
 (list 
  (make-elog-appender :category 'jdwp 
					  :priority 'trace
					  :layout "%H:%M:%S [%p] %c : %m%n" 
					  :output "*jdwp-log*")
  (make-elog-appender :category 'jdi
					  :priority 'trace
					  :layout "%H:%M:%S [%p] %c : %m%n" 
					  :output "*jdwp-log*")
  (make-elog-appender :category 'jdibug
					  :priority 'trace
					  :layout "%H:%M:%S [%p] %c : %m%n" 
					  :output "*jdwp-log*")))
@end example

Then redo the actions that have generated the bug.

Then save the content of the @code{*jdwp-log*} buffer into a file and
then send it to me, prefably compressed, as it can be quite huge.

@bye