The VM (especially the Debug and Checked versions) supports some options that
help debug programs running on it.  See invocation.txt for details.  However,
if the VM goes down with a segmentation fault, an assertion error etc. it
can be useful to debug the VM in gdb.  

See configurations.txt on how to activate constant garbage collection which
can be useful in order to root out garbage collection errors using the gdb
techniques in this file.  See UseOfC++.txt on the way we manage garbage
collection.

This document does not replace the standard gdb documentation!  See 
http://www.gnu.org/software/gdb/documentation/
and
http://sources.redhat.com/gdb/current/onlinedocs/gdb_toc.html

Debugging the VM under gdb is done in the following way:


1) You need to know where the VM is and where the base component is.
   Normally you will find the VM in palcom/developer/runtime/pal-vm/Linux-Checked/pal-vm
   Normally you will find the base component in palcom/developer/dev-lib/ist.palcom.base.prc

2) Start gdb with the command:
   gdb --args /path/to/the/vm -base /path/to/the/base/component -cp .:/path/to/dev-lib <otherparameters> <componentname>

3) Place a breakpoint in the 'exit' routine.  This means that if the program
   hits an assertion error it will stop before exiting, which gives you a
   chance to look at what happened using gdb.
   b exit
   If gdb asks "Make breakpoint pending on future shared library load?" then
   answer 'y'.

4) Place breakpoints as needed.  For example, to stop at a certain line
   in a certain file:
      b Class.cpp:123

5) Run the program, using the 'run' command.  You can restart the program
   at any time using this command, and gdb will notice if a new version of
   the program has been compiled.  It is a good idea not to exit and restart
   gdb too often as it does not save command history across restarts.

6) When the program is stopped, the C++ stack trace can be inspected using
   the 'where' instruction, and you can move up and down the stack frames
   with the 'up' and 'down' instructions.  Useful commands include:

   c  continue execution
   n  step forward (skip function calls)
   s  step forward (step into function calls)

   Variables can be inspected using the print command.  All object
   pointers inherit from the Object* type, which defines a print() method
   (in Debug versions of the VM).  So you can type:

   print x->print();

   to get basic information on the type of an object, and its value if it
   is one of the basic types (Integer, String, Symbol, etc.).  Once you
   know the type, you can cast it to that type and get access to the
   methods of that type.  For example if your thing is a component:

   print Component::cast(thing)->nameGet()->asCharStar()

   gives the name of a component, even if the thing variable is declared
   as an Object*.  The asCharStar() method, defined on Symbol, converts
   a symbol to a char* type, which is the kind of string that gdb can
   understand and print out.

   All classes have some properties, defined using the PROPERTY macro
   in their hpp fields.  These can be read under gdb using the
   ->nameGet() metods.  For example to get the name of the component of
   the class of an object you write

   print ((HeapObject*)thing)->clarseGet()->componentGet()->nameGet()->asCharStar()

   Arrays can be inspected with the at() method:

   print array->at(0)->print()

7) Using the asCharStar() method, you can make conditional breakpoints
   that trigger when a certain Symbol is encountered.  Thus:

   b Component.cpp:345
   condition 2 !strcmp(this->nameGet()->asCharStar(), "ist.palcom.frobber")

   will create a new breakpoint (we assume this is breakpoint number 2) and
   make it conditional so that it only breaks if the current object (this),
   which is assumed to be declared as a component, has the given name.

8) You can Ctrl-C the program at any point in the debugger, set the trace
   flag (to trace bytecodes executed) and then let it continue:

   Ctrl-C
   Use up command to find a stack frame in Interpreter.cpp
   set trace=0
   c
