This file should be called CAVEATS, not README, but I decided a
different name would only confuse people.

ldb is a retargetable debugger for ANSI C.  It has been shown to be
very easy to retarget from machine to machine.  I believe it should
also be easy to support different target languages, but I have not
amassed much evidence to convince you.

ldb is a *research* *prototype*.  You might find it useful if:
  - you are interested in debugging, e.g., you want a simple low-level
    platform on which to build a high-level debugger.
  - you are porting lcc to a new platform, perhaps an embedded
    platform without debugger support, and a cross-architecture
    teledebugger might come in handy
  - you want to build a debugger for a language you control, with
    minimum effort
If you just need a debugger, use gdb or dbx.

An essential premise of ldb's design is that the compiler has most of
the machine-dependent information the debugger needs, so the compiler
should be the one to provide it.  ldb's debugging-symbol format is
designed expressly to support retargeting (and multi-language
debugging), and it is *not* backward-compatible with formats designed
for gdb, dbx, or with DWARF.  You can't use ldb unless you have a
compiler that has been altered to emit these symbols.

I have altered Hanson and Fraser's lcc compiler to emit debugging
symbols used by ldb.  The current distribution works with lcc version 3.2.
For historical reasons, ldb does not support lcc's x86 target, and lcc
no longer supports ldb's 68000 and VAX targets.

ldb is written using `noweb', a tool for ``literate programming.''
It's not a very literate program, though---the only parts I've
expended much effort documenting are the ``hard parts.''  
Most of the system is written in Modula-3, but parts are also
written in C, Icon, PostScript, and two special-purpose languages.
You must install DEC SRC Modula-3, version 3, noweb, Icon, and lcc (or
alter another C compiler to make it compatible).  I supply the
PostScript and the special-purpose languages.

Look here:
  noweb    http://www.cs.purdue.edu/homes/nr/noweb or
	   ftp.shsu.edu:tex-archive/web/noweb 
  Icon	   http://www.cs.arizona.edu/icon/www or
	   ftp.cs.arizona.edu:icon
  Modula-3 http://www.research.digital.com/SRC/modula-3/html/home.html
  lcc	   http://www.cs.princeton.edu/software/lcc
	   ftp.cs.princeton.edu:pub/lcc?

As should be clear, a working ldb system requires more than a single
program.  The parts are:
  - lcc, which compiles C into assembly code and emits debugging
    symbols in PostScript
  - a `debug nub', which is linked with target programs and which 
    provides debugging services using an interface that is (nearly)
    independent of the target operating system
  - ldb proper, which is written in Modula-3.  ldb itself is made from
    a number of pieces held together with chewing gum and baling
    wire.  One such piece that should be useful independently is an
    interpreter for a subset of PostScript.
  - ldb-expserver-c, which is an ``expression-evalation server'' that
    compiles C expressions into PostScript code to provide expression
    evaluation at debug time.  The expression server is based on an
    old lcc front end.
  - a collection of PostScript files that are interpreted at run time
Other parts are used during the build process.

ldb is built using the Modula-3 m3build program.  A twisty collection
of impenetrable quake code mostly gets the parts in the right places
and properly hooked together.  Because this is a first release, it
probably won't build.  Please write me, nr@cs.purdue.edu, with
complaints and suggestions.


What's here:

doc		Documentation for ldb, all of which is out of date
src		noweb source used to biuld ldb and other parts
lcc-3.2-patch	a patchfile to apply to lcc before building it

