Initial revision

1 files changed, 259 insertions, 0 deletions

diff --git a/gdb/README b/gdb/README
new file mode 100644
index 0000000..999db4a
--- /dev/null
+++ b/gdb/README
@@ -0,0 +1,259 @@
+This is GDB, the GNU source-level debugger, presently running under
+un*x.  This is a pre-alpha version of GDB version 4, and has NOT been
+extensively tested.  It surely has some bugs, both bugs that were
+present in version 3 and new bugs.  I have filed all the bug reports
+and fixes mailed to bug-gdb, and the fixes in particular will move
+into these sources as I find the time.
+
+	      => THIS VERSION IS PARTICULARLY FRAGILE! <=
+
+	It depends on a preliminary version of a new "binary file
+	descriptor" library and a new global "include" directory, which
+	are packaged separately from GDB.  You must obtain, configure
+	and build this library manually, then configure and build gdb.
+	When building gdb's for multiple platforms, you must manually
+	rebuild the bfd library separately for each platform.  Yes, of
+	course, we are working on this!  FIXME!
+
+	Configure bfd for your host system by:
+
+		cd ../bfd
+		edit Makefile
+		make
+
+	Then you can cd ../gdb-whatever, and config and build gdb.
+
+This release moves the generic GNU include files, the BFD library,
+and the getopt routines into the parent directory of gdb.  The idea
+is that a variety of GNU tools can share a common copy of these things.
+
+A summary of features new since gdb-3.5 is in the file `WHATS.NEW'.
+
+The best way to build GDB, in my opinion, is in a subdirectory.  I use
+a naming convention "=XXX" where XXX is the machine type I'm building
+for.  Nothing depends on this, it's just how I remember which
+subdirectories are what.  So, once you have the BFD library built for
+that machine, you can do:
+
+	cd gdb-x.yy	(the directory where this README is)
+	mkdir =XXX	(e.g. mkdir =vax)
+	cd =XXX
+	../config.gdb machine
+	make
+
+Machine is like "vax" or "sun4".  For more information type `../config.gdb'.
+
+Once you have done that, just `make' will do everything, producing an
+executable `gdb' in this directory.
+
+You can also build gdb binaries in a completely different directory from its 
+sources, by specifying "srcdir=YYY" to config.gdb, giving it an absolute
+or relative path to the source directory.  
+
+GDB can be used as a cross-debugger, running on a machine of one type
+while debugging a program running on a machine of another type.  You
+configure it this way by specifying `config.gdb host target' where host
+is where GDB runs, and target is where your program runs.
+
+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.
+For details see the texinfo manual (distributed with emacs and as a
+printed manual).
+
+About languages other than C...
+
+C++ support has been integrated into gdb.  GDB should work with FORTRAN
+programs (if you have problem, please send a bug report; note that you
+may have to refer to some FORTRAN variables with a trailing
+underscore), 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++.  Pascal programs
+which use sets, subranges, file variables, or nested functions will not
+currently work.
+
+About kernel debugging...
+
+I have't done this myself so I can't really offer any advice.
+Remote debugging over serial lines is more like to be in a currently
+functioning state than the standalone gdb (kdb).  FIXME.
+
+About remote debugging...
+
+[This section seems to be out of date, I have never seen the "rapp"
+program, though I would like to.  FIXME.]
+`rapp' runs under unix and acts as a remote stub (like remote-multi.shar
+distributed with GDB version 3).  Currently it just works over UDP
+(network), not over a serial line.  To get it running
+* Compile GDB on the host machine as usual
+* Compile rapp on the target machine, giving for both host and target
+  the type of the target machine
+* Install "gdb" in /etc/services on both machines.
+
+This will get reworked before the initial release of 4.x.  FIXME.
+
+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.
+
+The files remote-eb.c and remote-nindy.c are two examples of remote
+interfaces for talking to existing ROM monitors (for the AMD 29000 and the
+Intel 960 repsectively).  There is also a remote interface for the
+VxWorks realtime kernel, which communicates over TCP/IP, in remote-vx.c
+and the vx-share subdirectory.
+
+About reporting bugs...
+
+The correct address for reporting bugs found with gdb is
+"bug-gdb@prep.ai.mit.edu".  Please email all bugs to that address.
+
+About xgdb...
+
+Hopefully a new xgdb will be in 4.x.
+
+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.  See
+XGDB-README for one person's opinion about what is wrong with the
+current xgdb.  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
+(Try typing M-x gdb RETURN).  Comments on this mode are welcome.
+
+About the machine-dependent files...
+
+tconfig/<machine>
+This contains Makefile stuff for when the target system is <machine>.
+It also specifies the name of the tm-XXX.h file for this machine.
+
+xconfig/<machine>
+This contains Makefile stuff for when the host system is <machine>.
+It also specifies the name of the xm-XXX.h file for this machine.
+
+tm-XXX.h (tm.h is a link to this file, created by config.gdb).
+This file contains macro definitions that express information
+about the target machine's registers, stack frame format and instructions.
+
+xm-XXX.h (xm.h is a link to this file, created by config.gdb).
+This contains macro definitions describing the host system environment,
+such as byte order, host C compiler and library, ptrace support,
+and core file structure.
+
+<machine>-opcode.h
+<machine>-pinsn.c
+These files contain the information necessary to print instructions
+for your cpu type.  <machine>-opcode.h includes some large initialized
+data structures, which is strange for a ".h" file, but it's OK since
+it is only included in one place.  <machine>-opcode.h is shared
+between the debugger and the assembler (if the GNU assembler has been
+ported to that machine), whereas <machine>-pinsn.c is specific to GDB.
+
+<machine>-tdep.c
+This file contains any miscellaneous code required for this machine
+as a target.  On some machines it doesn't exist at all.  Its existence
+is specified in the tconfig/XXX file.
+
+<machine>-xdep.c
+This file contains any miscellaneous code required for this machine
+as a host.  On some machines it doesn't exist at all.  Its existence
+is specified in the xconfig/XXX file.
+
+infptrace.c
+This is the low level interface to inferior processes for systems
+using the Unix ptrace call in a vanilla way.  Some systems have their
+own routines in <machine>-xdep.c.  Whether or not it is used
+is specified in the xconfig/XXX file.
+
+coredep.c
+Machine and system-dependent aspects of reading core files.  Some
+machines use coredep.c; some have the routines in <machine>-xdep.c.
+Whether or not it is used is specified in the xconfig/XXX file.
+Now that BFD is used to read core files, virtually all machines should
+use coredep.c and should just provide fetch_core_registers in
+<machine>-xdep.c.
+
+exec.c 
+Machine and system-dependent aspects of reading executable files.
+Some machines use exec.c; some have the routines in <machine>-tdep.c
+Since BFD, virtually all machines should use exec.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.
+
+If you make substantial changes, you'll have to file a copyright
+assignment with the Free Software Foundation before we can produce a
+release that includes your changes.  Send mail requesting the copyright
+assignment to gnu@prep.ai.mit.edu.  Do this early, like before the
+changes actually work, or even before you start them, because a manager
+or lawyer on your end will probably make this a slow process.
+
+Please try to avoid making machine-specific changes to
+machine-independent files.  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 be
+conditionalized on a specific feature of an operating system (set in
+tm.h or xm.h) rather than something like #if defined(vax) or #if
+defined(SYSV).  If you use an #ifdef on some symbol that is defined
+in a header file (e.g. #ifdef TIOCSETP), *please* make sure that you
+have #include'd the relevant header file in that module!
+
+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 BSD 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 BSD format.
+
+Please avoid duplicating code.  For example, in GDB 3.x all the stuff
+in infptrace.c was duplicated in *-dep.c, and so changing something
+was very painful.  Thus in GDB 4.x these have all been consolidated
+into infptrace.c.  infptrace.c can deal with variations between
+systems the same way any system-independent file would (hooks, #if
+defined, etc.), and machines which are radically different don't need
+to use infptrace.c at all.  The same was true of core_file_command
+and exec_file_command.
+
+About debugging gdb with itself...
+
+You probably want to do a "make TAGS" after you configure your
+distribution; this will put the machine dependent routines for your
+local machine where they will be accessed first by a M-period .
+
+Also, make sure that you've compiled gdb with your local cc or taken
+appropriate precautions regarding ansification of include files.  See
+the Makefile for more information.
+
+When you run gdb in this directory, it will read a ".gdbinit" file that
+sets up some simple things to make debugging gdb easier.  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 details.
+
+(this is for editing this file with GNU emacs)
+Local Variables:
+mode: text
+End: