-*-text-*-

    The file vgdb-patch contains a patch to GNU gdb 4.12 to enable
    working on AtFS versions. This patch works on SPARC machines
    running SunOS 4.1.2 and is not tested with other platforms yet.


What it does:

    This patch turns GNU gdb into "Vgdb" -- a debugger that can work
    on AtFS versions of source files as well as on "normal" sources.

    Vgdb is capable to do source-level debugging on C programs
    compiled with shape directly from an archive. Provided the C files
    have been compiled with shape's default rule, gdb automagically
    identifies the versions the binary has been compiled from if it
    has been compiled from non-busy source files.

    Together with GNU Emacs and the find-atfs package for Emacs, you
    can use Emacs' gdb-mode with Vgdb such that Emacs displays the
    appropriate source version in the source window. Just set the
    Emacs variable gdb-command-name to the name of the Vgdb
    executable, e.g. with '(setq gdb-command-name "vgdb")' in your
    ~/.emacs file.

    Gdb's normal capabilities are not in any way affected by this
    patch -- you can use Vgdb exactly like you have used gdb before.
    

How to apply the patch:

    Unpack the gdb 4.12 distribution. This should create a directory
    named gdb-4.12. Change to this directory and configure gdb for your
    machine by invoking "configure".  Copy the file vgdb-patch into
    this directory and patch the source files with

	"patch -p0 < vgdb-patch".

    Please note that the "-p0" switch is important -- the patch will
    not succeed without it.

    Set the SHAPETOOLS environment variable to the base path where
    you installed the ShapeTools stuff (e.g. /usr/local).

    Now type "make". This should build an executable "gdb" in the gdb
    directory. You may want to rename the executable to "vgdb".

    If you want to apply the patch to a different version of GNU gdb,
    you may have to modify the sources by hand, we haven't tried it.


Problems:

    Due to some irregularities in the declarations of external
    functions, the vgdb-patch currently works only with Sun's C
    compiler, not with gcc.

    If Vgdb is working on a version with attribute citations that
    expand to more than a single line, it will display the wrong
    source context when used stand-alone. (Vgdb does not expand
    attributes when it reads the source file.) To avoid this, use Vgdb
    with GNU Emacs' gdb-mode and the find-atfs package. (This is the
    morally superior way of debugging anyway.)
