gdb-3.3

1 files changed, 107 insertions, 34 deletions

diff --git a/gdb/README b/gdb/README
index d45a905ee1..633b4f9ba4 100644
--- a/gdb/README
+++ b/gdb/README
@@ -1,30 +1,127 @@
-This is GDB, a source-level debugger intended for GNU,
-presently running under un*x.
+This is GDB, the GNU source-level debugger, presently running under un*x.
 
-Before compiling GDB, you must set up links to five files according to
-the kind of machine you are running on.  To do this, type `config.gdb
-machine', where machine is something like `vax' or `sun2'.  This
-creates links named `param.h', `opcode.h', `pinsn.c', and `infdep.c'.
+Before compiling GDB, you must tell GDB what kind of machine you are
+running on.  To do this, type `config.gdb machine', where machine is
+something like `vax' or `sun2'.  For a list of valid machine types,
+type `config.gdb'.
+
+Normally config.gdb edits the makefile as necessary.  If you have to
+edit the makefile on a standard machine listed in config.gdb this
+should be considered a bug and reported as such.
 
 Once these files are set up, just `make' will do everything,
 producing an executable `gdb' in this directory.
 
-About the machine-dependent files...
+If you want a new (current to this release) version of the manual, you
+will have to use the gdb.texinfo file provided with this distribution.
+The gdb.texinfo file requires the texinfo-format-buffer command from
+emacs 18.55 or later.
+
+About languages other than C...
+
+C++ support has been integrated into gdb.  GDB should work with Pascal
+and FORTRAN programs, but I am not aware of anyone who is working on
+getting it to use the syntax of any language other than C or C++.
+
+About -gg format...
+
+Currently GDB version 3.x does *not* support GCC's -gg format.  This
+is because it is (in theory) has fast enough startup on dbx debugging
+format object files that -gg format is unnecessary (and hence
+undesirable, since it wastes space and processing power in gcc).  I
+would like to hear people's opinions on the amount of time currently
+spent in startup; is it fast enough?
+
+About remote debugging...
+
+The two files remote-multi.shar and remote-sa.m68k.shar contain two
+examples of a remote stub to be used with remote.c.  The the -multi
+file is a general stub that can probably be running on various
+different flavors of unix to allow debugging over a serial line from
+one machine to another.  The remote-sa.m68k.shar is designed to run
+standalone on a 68k type cpu and communicate properley with the
+remote.c stub over a serial line.
+
+About reporting bugs...
+
+The correct address for reporting bugs found with gdb is
+"bug-gdb@prep.ai.mit.edu".  Please send all bugs to that address.
+
+About xgdb...
+
+xgdb.c was provided to us by the user community; it is not an integral
+part of the gdb distribution.  The problem of providing visual
+debugging support on top of gdb is peripheral to the GNU project and
+(at least right now) we can't afford to put time into it.  So while we
+will be happy to incorporate user fixes to xgdb.c, we do not guarantee
+that it will work and we will not fix bugs reported in it.  Someone is
+working on writing a new XGDB, so improving (e.g. by fixing it so that
+it will work, if it doesn't currently) the current one is not worth it.
+
+For those intersted in auto display of source and the availability of
+an editor while debugging I suggest trying gdb-mode in gnu-emacs.
+Comments on this mode are welcome.
 
-m-<machine>.h
+About the machine-dependent files...
 
+m-<machine>.h (param.h is a link to this file).
 This file contains macro definitions that express information
 about the machine's registers, stack frame format and instructions.
 
-<machine>-opcode.h, <machine>-pinsn.c
+<machine>-opcode.h (opcode.h is a link to this file).
+<machine>-pinsn.c (pinsn.c is a link to this file).
 These files contain the information necessary to print instructions
 for your cpu type.
 
-<machine>-dep.c
+<machine>-dep.c (dep.c is a link to this file).
 Those routines which provide a low level interface to ptrace and which
 tend to be machine-dependent.  (The machine-independent routines are in
 `infrun.c' and `inflow.c')
 
+About writing code for GDB...
+
+We appreciate having users contribute code that is of general use, but
+for it to be included in future GDB releases it must be cleanly
+written.  We do not want to include changes that will needlessly make future
+maintainance difficult.  It is not much harder to do things right, and
+in the long term it is worth it to the GNU project, and probably to
+you individually as well.
+
+Please code according to the GNU coding standards.  If you do not have
+a copy, you can request one by sending mail to gnu@prep.ai.mit.edu.
+
+Please try to avoid making machine-specific changes to
+machine-independent files (i.e. all files except "param.h" and
+"dep.c".  "pinsn.c" and "opcode.h" are processor-specific but not
+operating system-dependent).  If this is unavoidable, put a hook in
+the machine-independent file which calls a (possibly)
+machine-dependent macro (for example, the IGNORE_SYMBOL macro can be
+used for any symbols which need to be ignored on a specific machine.
+Calling IGNORE_SYMBOL in dbxread.c is a lot cleaner than a maze of
+#if defined's).  The machine-independent code should do whatever "most"
+machines want if the macro is not defined in param.h.  Using #if defined
+can sometimes be OK (e.g.  SET_STACK_LIMIT_HUGE) but should usually be
+conditionalized on a specific feature of an operating system (set in
+param.h) rather than something like #if defined(vax) or #if defined(SYSV).
+
+It is better to replace entire routines which may be system-specific,
+rather than put in a whole bunch of hooks which are probably not going
+to be helpful for any purpose other than your changes.  For example,
+if you want to modify dbxread.c to deal with DBX debugging symbols
+which are in COFF files rather than a.out files, do something
+along the lines of a macro GET_NEXT_SYMBOL, which could have
+different definitions for COFF and a.out, rather than trying to put
+the necessary changes throughout all the code in dbxread.c that
+currently assumes a.out format.
+
+Please avoid duplicating code.  For example, if something needs to be
+changed in read_inferior_memory, it is very painful because there is a
+copy in every dep.c file.  The correct way to do this is to put the
+standard ptrace interfaces in a separate file ptrace.c, which is used
+by all systems which have ptrace.  ptrace.c would deal with variations
+between systems the same way any system-independent file would (hooks,
+#if defined, etc.).
+
 About debugging gdb with itself...
 
 You probably want to do a "make TAGS" after you configure your
@@ -41,27 +138,3 @@ The "info" command, when executed without a subcommand in a gdb being
 debugged by gdb, will pop you back up to the top level gdb.  See
 .gdbinit for more details.
 
-About languages other than C...
-
-C++ support has been integrated into gdb; it works, but somewhat
-buggily.  Pascal support has not yet been integrated in gdb; the work
-is being done.
-
-About reporting bugs...
-
-The correct address for reporting bugs found with gdb is
-"bug-gdb@prep.ai.mit.edu".  Please send all bugs to that address.
-
-About xgdb...
-
-xgdb.c was provided to us by the user community; it is not an integral
-part of the gdb distribution.  The problem of providing visual
-debugging support on top of gdb is peripheral to the GNU project and
-(at least right now) we can't afford to put time into it.  So while we
-will be happy to incorporate user fixes to xgdb.c, we do not guarantee
-that it will work and we will not fix bugs reported in it.
-
-For those intersted in auto display of source and the availability of
-an editor while debugging I suggest trying gdb-mode in gnu-emacs.
-Comments on this mode are welcome.
-