Update README.

1 files changed, 269 insertions, 146 deletions

diff --git a/gdb/README b/gdb/README
index d052c99..a6e18eb 100644
--- a/gdb/README
+++ b/gdb/README
@@ -1,119 +1,146 @@
-		README for gdb-3.98 beta release
-		John Gilmore	      31 July 91
-
-This is GDB, the GNU source-level debugger, presently running under
-un*x.  This is a beta test 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.  If your favorite bugfix is not
-yet present here, I encourage you to port it into this version and
-then send the diffs to bug-gdb@prep.ai.mit.edu.
+		README for gdb-4.0 release
+	John Gilmore	 		23 Aug 91
 
+This is GDB, the GNU source-level debugger, presently running under un*x.
 A summary of features new since gdb-3.5 is in the file `WHATS.NEW'.
 
 
-		Unpacking and Installation
+Unpacking and Installation -- quick overview
+==========================
 
 This release moves the generic GNU include files, the BFD ("binary file
 description") library, the getopt routines, obstacks, and the readline
-library into the parent directory of gdb.  The idea is that a variety
-of GNU tools can share a common copy of these things.
+library into the parent directory of the gdb source files.  The idea is
+that a variety of GNU tools can share a common copy of these things.
 
-These generic files are packaged separately from GDB, in a tar file
-called "bfd.ilrt-3.98.tar.Z".  ("ilrt" stands for include, libiberty,
-readline, texinfo).  Unpack that tar file in the same directory in
-which you unpacked the gdb-3.98.tar.Z file, so that for example the
-'bfd' directory sits next to the 'gdb' directory.  The whole top-level
-directory will look like this with `ls -F':
+These generic files are packaged together with the directory containing
+the source code for GDB, for now.  When you unpack the gdb-4.0.tar.Z
+file, you'll get a directory called `gdb-4.0', which contains:
 
-  Makefile.in       configure*        include/          texinfo/
-  README.configure  configure.in      libiberty/
-  bfd/              gdb/              readline/
+  Makefile.in       bfd/              configure.in      libiberty/
+  README            config.sub*       gdb/              readline/
+  README.configure  configure*        include/          texinfo/
 
-Once you have this stuff unpacked, and your current directory is here,
-you can type:
+To build GDB, you can just do:
 
+	cd gdb-4.0
 	./configure HOSTNAME
 	make
+	cp gdb/gdb /usr/local/bin/gdb	(or wherever you want)
 
-and all the libraries, as well as GDB will be configured and built.
+This will configure and build all the libraries as well as GDB.
 If you get compiler warnings during this stage, see the `Reporting Bugs'
 section below; there are a few known problems.
 
 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 `./configure host -target=target';
-see below.
+while debugging a program running on a machine of another type.  See below.
+
+
+More Documentation
+==================
+
+   The GDB 4.0 release includes an already-formatted reference card, ready
+for printing on a PostScript printer, as `gdb-4.0/gdb/refcard.ps'.  It
+uses the most common PostScript fonts: the Times family, Courier,
+and Symbol.  If you have a PostScript printer you can print the
+reference card by just sending `refcard.ps' to the printer.
+
+   The release also includes the online Info version of the manual
+already formatted: the main Info file is `gdb-4.0/gdb/gdb.info', and
+it refers to subordinate files matching `gdb.info*' in the same
+directory.
+
+   If you want to make these Info files yourself from the GDB
+manual's source, you need the GNU `makeinfo' program.  Once you have
+it, you can type
+
+     cd gdb-4.0/gdb
+     make gdb.info
+
+to make the Info file.
+
+   If you want to format and print copies of this manual, you need
+several things:
+
+   * TeX, the public domain typesetting program written by Donald
+     Knuth, must be installed on your system and available through
+     your execution path.
+
+   * `gdb-4.0/texinfo': TeX macros defining the GNU Documentation
+     Format.
+
+   * *A DVI output program.*  TeX doesn't actually make marks on
+     paper; it produces output files called DVI files.  If your
+     system has TeX installed, chances are it has a program for
+     printing out these files; one popular example is `dvips', which
+     can print DVI files on PostScript printers.
+
+Once you have these things, you can type
 
+     cd gdb-4.0/gdb
+     make gdb.dvi
 
-		More Documentation
+to format the text of this manual, and print it with the usual output
+method for TeX DVI files at your site.
 
-The GDB manual is much expanded and improved.  For online browsing,
-gdb/gdb.info is the main file, and there are gdb/gdb.info-1 through -6
-files that can be installed into your main `info' tree.  If you want a
-printed version of the manual, you can run, from the GDB source
-directory,
+   If you want to print the reference card, but don't have a PostScript
+printer, or want to print using Computer Modern fonts instead, you can
+still print it if you have TeX.  Format the reference card by typing
 
-	make gdb.dvi
+     cd gdb-4.0/gdb
+     make refcard.dvi
 
-to make the TeX device-independent output file.  This assumes you have
-a running TeX on your system.  The source for the GDB manual is in
-doc/gdb.texinfo (and a few other files it includes), provided with
-this distribution.  The Makefile attempts to use the texinfo.tex
-supplied as part of the BFD-and-libraries tar file, since the manual
-uses Texinfo-2 which is not in common use yet.
+The GDB reference card is designed to print in landscape mode on US
+"letter" size paper; that is, on a sheet 11 inches wide by 8.5
+inches high.  You will need to specify this form of printing as an
+option to your DVI output program.
 
 
-		Configuration Details (extracted from gdb.texinfo)
+Installing GDB
+==============
 
-   GDB is distributed with a `configure' script that automates the
-process of preparing GDB for installation; you can then use `make'
-to build the `gdb' program.
+   GDB comes with a `configure' script that automates the process of
+preparing GDB for installation; you can then use `make' to build the
+`gdb' program.
 
-   The `configure' script that's specific to GDB is distributed in
-the main GDB source directory.  However, building GDB also requires
-several other directories of source common to multiple GNU programs.
-These directories (GNU libraries and includes) are distributed
-separately, but their `configure' scripts and `Makefile's are
-designed to work together.  To ensure that GDB's `Makefile' can find
-all the pieces, you should make a single overall directory to hold
-the directories of source for GNU libraries and includes, and you
-should install the GDB source directory there too.  In this
-Appendix, we refer to the directory of GNU source directories as GNUSRC.
+   The gdb distribution includes all the source code you need for gdb
+in a single directory `gdb-4.0'.  That directory in turn contains:
 
-   At a minimum, to build GDB you need the directories
+`gdb-4.0/configure'
+     Overall script for configuring GDB and all its supporting
+     libraries.
 
-`GNUSRC/gdb'
+`gdb-4.0/gdb'
      the source specific to GDB itself
 
-`GNUSRC/bfd'
+`gdb-4.0/bfd'
      source for the Binary File Descriptor Library
 
-`GNUSRC/include'
+`gdb-4.0/include'
      GNU include files
 
-`GNUSRC/libiberty'
+`gdb-4.0/libiberty'
      source for the `-liberty' free software library
 
-`GNUSRC/readline'
+`gdb-4.0/readline'
      source for the GNU command-line interface
 
-Each of these directories has its own `configure' script.  GNUSRC has
-an overall `configure' script, which is distributed with the GNU
-libraries and includes.
+Each of these directories has its own `configure' script, which are
+used by the overall `configure' script in `gdb-4.0'.
 
-   `configure' is designed to be called recursively, so it is most
-convenient to run `configure' from the GNUSRC directory.  The
-simplest way to configure and build GDB is the following:
+   It is most convenient to run `configure' from the `gdb-4.0'
+directory.  The simplest way to configure and build GDB is the
+following:
 
-     cd GNUSRC
+     cd gdb-4.0
      ./configure HOST
      make
 
-where HOST is something like `sun4' or `vax', that identifies the
-platform where GDB will run.  This builds the three libraries `bfd',
-`readline', and `libiberty', then `gdb' itself.  The configured
-source files, and the binaries, are left in the corresponding source
-directories.
+where HOST is something like `sun4' or `decstation', that identifies
+the platform where GDB will run.  This builds the three libraries
+`bfd', `readline', and `libiberty', then `gdb' itself.  The
+configured source files, and the binaries, are left in the
+corresponding source directories.
 
    You can install `gdb' anywhere; it has no hardwired paths. 
 However, you should make sure that the shell on your path (named by
@@ -121,122 +148,216 @@ the `SHELL' environment variable) is publicly readable; some systems
 refuse to let GDB debug child processes whose programs are not
 readable, and GDB uses the shell to start your program.
 
-
-		Configuration Subdirectories
-
-   If you build GDB for several host or target machines, and if your
-`make' program handles the `VPATH' feature (GNU `make' does), it is
-most convenient instead to build the different GDB configurations in
-subdirectories (separate from the source).  `configure' does this
-for you when you simultaneously specify several configurations; but
-it's a good habit even for a single configuration.  You can specify
-the use of subdirectories using the `+forcesubdirs' option
-(abbreviated `+f').  For example, you can build GDB on a Sun 4 as
-follows:
-
-     cd GNUSRC
-     ./configure +f sun4
-     cd Host-sun4/Target-sun4
+Configuration Subdirectories
+============================
+
+   If you want to run GDB versions for several host or target
+machines, you'll need a different gdb compiled for each combination
+of host and target.  `configure' is designed to make this easy by
+allowing you to generate each configuration in a separate
+subdirectory.  If your `make' program handles the `VPATH' feature
+(GNU `make' does), running `make' in each of these directories then
+builds the gdb program specified there.
+
+   `configure' creates these subdirectories for you when you
+simultaneously specify several configurations; but it's a good habit
+even for a single configuration.  You can specify the use of
+subdirectories using the `+subdirs' option (abbreviated `+sub'). 
+For example, you can build GDB on a Sun 4 as follows:
+
+     cd gdb-4.0
+     ./configure +sub sun4
+     cd Host-sparc-sun-sunos4/Target-sparc-sun-sunos4
      make
 
    When `configure' uses subdirectories to build programs or
-libraries, it creates nested directories `Host-HOST/Target-MACHINE'.
-This is because GDB can be configured for cross-compiling: GDB can
-run on one machine (the host) while debugging programs that run on
-another machine (the target).  You specify cross-debugging targets
-by giving the `+target=MACHINE' option to `configure'.  Specifying
-only hosts still gives you two levels of subdirectory for each host,
-with the same machine-name suffix on both.  On the other hand,
-whenever you specify both hosts and targets on the same command
-line, `configure' creates all combinations of the hosts and targets you
-list.
+libraries, it creates nested directories `Host-HOST/Target-TARGET'. 
+(As you see in the example, the names used for HOST and TARGET may
+be expanded from your `configure' argument; *note Config Names::.).
+`configure' uses these two directory levels because GDB can be
+configured for cross-compiling: GDB can run on one machine (the
+host) while debugging programs that run on another machine (the
+target).  You specify cross-debugging targets by giving the
+`+target=TARGET' option to `configure'.  Specifying only hosts still
+gives you two levels of subdirectory for each host, with the same
+configuration suffix on both; that is, if you give any number of
+hosts but no targets, GDB will be configured for native debugging on
+each host.  On the other hand, whenever you specify both hosts and
+targets on the same command line, `configure' creates all
+combinations of the hosts and targets you list.
 
    When you run `make' to build a program or library, you must run it
 in a configured directory.  If you made a single configuration,
 without subdirectories, run `make' in the source directory.  If you
-have `Host-HOST/Target-MACHINE' subdirectories, run `make' in those
+have `Host-HOST/Target-TARGET' subdirectories, run `make' in those
 subdirectories.
 
    Each `configure' and `Makefile' under each source directory runs
-recursively, so that typing `make' in GNUSRC (or in a
-`GNUSRC/Host-HOST/Target-MACHINE' subdirectory) builds all the
+recursively, so that typing `make' in `gdb-4.0' (or in a
+`gdb-4.0/Host-HOST/Target-TARGET' subdirectory) builds all the
 required libraries, then GDB.
 
-   If you run `configure' from a directory (such as GNUSRC) that
+   If you run `configure' from a directory (such as `gdb-4.0') that
 contains source directories for multiple libraries or programs,
-`configure' creates the `Host-HOST/Target-MACHINE' subdirectories in
+`configure' creates the `Host-HOST/Target-TARGET' subdirectories in
 each library or program's source directory.  For example, typing:
 
-     cd GNUSRC
-     configure sun4 +target=vx960
+     cd gdb-4.0
+     configure sun4 +target=vxworks960
 
 creates the following directories:
 
-     GNUSRC/Host-sun4/Target-vx960
-     GNUSRC/bfd/Host-sun4/Target-vx960
-     GNUSRC/gdb/Host-sun4/Target-vx960
-     GNUSRC/libiberty/Host-sun4/Target-vx960
-     GNUSRC/readline/Host-sun4/Target-vx960
+     gdb-4.0/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks
+     gdb-4.0/bfd/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks
+     gdb-4.0/gdb/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks
+     gdb-4.0/libiberty/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks
+     gdb-4.0/readline/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks
+
+The `Makefile' in
+
+     gdb-4.0/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks
+
+will `cd' to the appropriate lower-level directories, for example:
 
-The `Makefile' in `GNUSRC/Host-sun4/Target-vx960' will `cd' to the
-appropriate lower-level directories (such as
-`GNUSRC/bfd/Host-sun4/Target-vx960'), building each in turn.
+     gdb-4.0/bfd/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks
+
+building each in turn.
 
    When you have multiple hosts or targets configured, you can run
 `make' on them in parallel (for example, if they are NFS-mounted on
 each of the hosts); they will not interfere with each other.
 
-
-		`configure' Options
+Specifying Names for Hosts and Targets
+======================================
+
+   The specifications used for hosts and targets in the `configure'
+script are based on a three-part naming scheme, but some short
+predefined aliases are also supported.  The full naming scheme
+encodes three pieces of information in the following pattern:
+
+     ARCHITECTURE-VENDOR-OS
+
+   For example, you can use the alias `sun4' as a HOST argument or in
+a `+target='TARGET option, but the full name of that configuration
+specifies that the architecture is `sparc', the vendor is `sun', and
+the operating system is `sunos4'.
+
+   The following table shows all the architectures, hosts, and OS
+prefixes that `configure' recognizes in GDB 4.0.  Entries in the "OS
+prefix"
+column ending in a `*' may be followed by a release number.
+
+
+     ARCHITECTURE  VENDOR        OS prefix
+     ------------+-------------+-------------
+                 |             |
+      a29k       | altos       | aix*
+      alliant    | aout        | aout
+      arm        | apollo      | bout
+      c1         | att         | bsd*
+      c2         | bout        | coff
+      i386       | coff        | ctix*
+      i860       | convergent  | dynix*
+      i960       | convex      | esix*
+      m68000     | dec         | hpux*
+      m68k       | encore      | isc*
+      m88k       | gould       | mach*
+      mips       | hp          | newsos*
+      ns32k      | ibm         | nindy*
+      pyramid    | intel       | none
+      rs6000     | isi         | osf*
+      rtpc       | little      | sco*    
+      sparc      | mips        | sunos*  
+      tahoe      | motorola    | sysv*   
+      tron       | ncr         | ultrix* 
+      vax        | next        | unos*   
+                 | none        | v88r*   
+                 | sco         | vms*    
+                 | sequent     | vxworks*
+                 | sgi         | 
+                 | sony        |
+                 | sun         |
+                 | unicom      |
+                 | utek        |
+                 | wrs         |
+
+     *Warning:* Many combinations of architecture, vendor, and OS are
+     untested.
+
+   The `configure' script accompanying GDB 4.0 does not provide any
+query facility to list all supported host and target names or
+aliases.  `configure' calls the Bourne shell script `config.sub' to
+map abbreviations to full names; you can read the script, if you
+wish, or you can use it to test your guesses on abbreviations--for
+example:
+
+     % sh config.sub sun4
+     sparc-sun-sunos4
+     % sh config.sub sun3
+     m68k-sun-sunos4
+     % sh config.sub decstation
+     mips-dec-ultrix
+     % sh config.sub hp300bsd
+     m68k-hp-bsd
+     % sh config.sub i386v
+     i386-none-sysv
+     % sh config.sub i486v
+     *** No vendor: configuration `i486v' not recognized
+
+`configure' Options
+===================
 
    Here is a summary of all the `configure' options and arguments
 that you might use for building GDB:
 
-     configure [+destdir=DIR] [+forcesubdirs] [+norecur] [+rm]
-               [+target=MACHINE...] HOST...
+     configure [+destdir=DIR] [+subdirs] [+norecur] [+rm]
+               [+target=TARGET...] HOST...
 
 You may introduce options with the character `-' rather than `+' if
-you prefer; but options introduced with `+' may be truncated.
+you prefer; but you may abbreviate option names if you use `+'.
 
 `+destdir=DIR'
      DIR is an installation directory *path prefix*.  After you
      configure with this option, `make install' will install GDB as
      `DIR/bin/gdb', and the libraries in `DIR/lib'.  If you specify
-    
      `+destdir=/usr/local', for example, `make install' creates
      `/usr/local/bin/gdb'.
 
-`+forcesubdirs'
+`+subdirs'
      Write configuration specific files in subdirectories of the form
 
-          Host-MACHINE/Target-MACHINE
+          Host-HOST/Target-TARGET
 
      (and configure the `Makefile' to write binaries there too). 
      Without this option, if you specify only one configuration for
      GDB, `configure' will use the same directory for source,
      configured files, and binaries.  This option is used
      automatically if you specify more than one HOST or more than
-     one `+target=MACHINE' option on the `configure' command line.
+     one
+     `+target=TARGET' option on the `configure' command line.
 
 `+norecur'
      Configure only the directory where `configure' is executed; do
      not propagate configuration to subdirectories.
 
 `+rm'
-     Remove the configuration specified by other arguments.
+     Remove the configuration that the other arguments specify.
 
-`+target=MACHINE ...'
+`+target=TARGET ...'
      Configure GDB for cross-debugging programs running on each
-     specified MACHINE.  You may specify as many `+target' options
-     as you wish.  To see a list of available targets, execute `ls
-     tconfig' in the GDB source directory.  Without this option, GDB
-     is configured to debug programs that run on the same machine
-     (HOST) as GDB itself.
+     specified TARGET.  You may specify as many `+target' options as
+     you wish.  Without this option, GDB is configured to debug
+     programs that run on the same machine (HOST) as GDB itself.
+
+     There is no convenient way to generate a list of all available
+     targets.
 
 `HOST ...'
      Configure GDB to run on each specified HOST.  You may specify as
-     many host names as you wish.  To see a list of available hosts,
-     execute `ls xconfig' in the GDB source directory.
+     many host names as you wish.
+
+     There is no convenient way to generate a list of all available
+     hosts.
 
 `configure' accepts other options, for compatibility with configuring
 other GNU tools recursively; but these are the only options that
@@ -248,10 +369,11 @@ affect GDB or its supporting libraries.
 C++ support has been integrated into gdb.  GDB should work with FORTRAN
 programs.  (If you have problems, please send a bug report; you may
 have to refer to some FORTRAN variables with a trailing underscore).
-There is an effort to produce a GDB that works with Modula-2.  I am not
-aware of anyone who is working on getting gdb to use the syntax of any
-other language.  Pascal programs which use sets, subranges, file
-variables, or nested functions will not currently work.
+Andrew Beers has produced a GDB that works with Modula-2, which will
+appear in gdb-4.1.  I am not aware of anyone who is working on getting
+gdb to use the syntax of any other language.  Pascal programs which use
+sets, subranges, file variables, or nested functions will not currently
+work.
 
 
 		Kernel debugging
@@ -298,17 +420,15 @@ distributed with GDB version 3).  Currently it just works over UDP
 The correct address for reporting bugs found in gdb is
 "bug-gdb@prep.ai.mit.edu".  Please email all bugs to that address.
 
-"mcheck.c", line 32, will produce a pointer conversion warning, which
-can be ignored.
-
-When gdb reads object files produced by the Sun bundled C compiler,
-you will often get a "bad block start address patched" message.  You
-can shut off such messages with the command `set complaint 0' (which
-you can put in your ~/.gdbinit if you like).  Messages like this
-during symbol reading indicate some mismatch between the object file
-and GDB's symbol reading code (in this case, it's a mismatch
-between the specs for the object file format, and what Sun's compiler
-actually outputs).
+GDB can produce warnings about symbols that it does not understand.  By
+default, these warnings are disabled.  You can enable them by executing
+`set complaint 10' (which you can put in your ~/.gdbinit if you like).
+I recommend doing this if you are working on a compiler, assembler,
+linker, or gdb, since it will point out problems that you may be able
+to fix.  Warnings produced during symbol reading indicate some mismatch
+between the object file and GDB's symbol reading code (in many cases,
+it's a mismatch between the specs for the object file format, and what
+the compiler actually outputs or the debugger actually understands).
 
 If you port gdb to a new machine, please send the required changes
 to bug-gdb@prep.ai.mit.edu.  If your changes are more than a few
@@ -453,6 +573,9 @@ 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.
 
+I strongly recommend printing out the reference card and using it.
+Send reference-card suggestions to bug-gdb@prep.ai.mit.edu, just like bugs.
+
 If you use emacs, you will 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