- README for gdb-4.4 release
- John Gilmore & Stu Grossman 31 Jan 1992
+ README for gdb-4.7 release
+ Stu Grossman & John Gilmore 23 October 1992
This is GDB, the GNU source-level debugger, presently running under un*x.
-A summary of new features is in the file `WHATS.NEW'.
+A summary of new features is in the file `NEWS'.
Unpacking and Installation -- quick overview
In this release, the GDB debugger sources, the generic GNU include
files, the BFD ("binary file description") library, the readline library,
-and a miscellaneous library all have directories of their own underneath
-the gdb-4.4 directory. The idea is that a variety of GNU tools can
+and other libraries all have directories of their own underneath
+the gdb-4.7 directory. The idea is that a variety of GNU tools can
share a common copy of these things. Configuration scripts and
makefiles exist to cruise up and down this directory tree and
automatically build all the pieces in the right order.
-When you unpack the gdb-4.4.tar.Z file, you'll get a directory called
-`gdb-4.4', which contains:
+When you unpack the gdb-4.7.tar.Z file, you'll get a directory called
+`gdb-4.7', which contains:
- DOC.configure bfd/ configure* glob/ readline/
- Makefile.in config/ configure.in include/ texinfo/
- README config.sub* gdb/ libiberty/
+ COPYING.LIB config/ configure.texi mmalloc/
+ Makefile.in config.sub* gdb/ move-if-change*
+ README configure* glob/ opcodes/
+ bfd/ configure.in include/ readline/
+ cfg-paper.texi configure.man libiberty/ texinfo/
To build GDB, you can just do:
- cd gdb-4.4
+ cd gdb-4.7
./configure HOSTTYPE (e.g. sun4, decstation)
make
cp gdb/gdb /usr/local/bin/gdb (or wherever you want)
More Documentation
-==================
+******************
- The GDB 4 release includes an already-formatted reference card,
-ready for printing on a PostScript or GhostScript printer, in the `gdb'
-subdirectory of the main source directory--in `gdb-4.4/gdb/refcard.ps'
-of the version 4.4 release. If you have a PostScript or GhostScript
-printer, you can print the reference card by just sending `refcard.ps'
-to the printer.
+ The GDB 4 release includes an already-formatted reference card, ready
+for printing with PostScript or GhostScript, in the `gdb' subdirectory
+of the main source directory--in `gdb-4.7/gdb/refcard.ps' of the
+version 4.7 release. If you can use PostScript or GhostScript with your
+printer, you can print the reference card immediately with `refcard.ps'.
- If all you have is TeX, format the GDB reference card by typing:
+ The release also includes the source for the reference card. You
+can format it, using TeX, by typing:
make refcard.dvi
high. You will need to specify this form of printing as an option to
your DVI output program.
- All the documentation for GDB comes as part of the online
-distribution. The documentation is written in Texinfo format,
-which is a documentation system that uses a single source file to
-produce both on-line information and a printed manual. You can use
-one of the Info formatting commands to create the on-line version of
-the documentation and TeX (or `texi2roff') to typeset the printed
-version.
+ All the documentation for GDB comes as part of the machine-readable
+distribution. The documentation is written in Texinfo format, which is
+a documentation system that uses a single source file to produce both
+on-line information and a printed manual. You can use one of the Info
+formatting commands to create the on-line version of the documentation
+and TeX (or `texi2roff') to typeset the printed version.
- GDB includes an already formatted copy of the on-line Info version
-of this manual in the `gdb' subdirectory. The main Info file is
+ GDB includes an already formatted copy of the on-line Info version of
+this manual in the `gdb' subdirectory. The main Info file is
`gdb-VERSION-NUMBER/gdb/gdb.info', and it refers to subordinate files
-matching `gdb.info*' in the same directory.
+matching `gdb.info*' in the same directory. If necessary, you can
+print out these files, or read them with any editor; but they are
+easier to read using the `info' subsystem in GNU Emacs or the
+standalone `info' program, available as part of the GNU Texinfo
+distribution.
If you want to format these Info files yourself, you need one of the
-Info formatting programs, such as `texinfo-format-buffer' or
-`makeinfo'.
+Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
If you have `makeinfo' installed, and are in the top level GDB
-source directory (`gdb-4.4', in the case of version 4.4), you can make
+source directory (`gdb-4.7', in the case of version 4.7), you can make
the Info file by typing:
cd gdb
TeX also requires a macro definitions file called `texinfo.tex'.
This file tells TeX how to typeset a document written in Texinfo
-format. On its own, TeX cannot read, much less typeset a Texinfo
-file. `texinfo.tex' is distributed with GDB and is located in the
+format. On its own, TeX cannot read, much less typeset a Texinfo file.
+ `texinfo.tex' is distributed with GDB and is located in the
`gdb-VERSION-NUMBER/texinfo' directory.
- If you have TeX and a DVI printer program installed, you can
-typeset and print this manual. First switch to the the `gdb'
-subdirectory of the main source directory (for example, to
-`gdb-4.4/gdb') and then type:
+ If you have TeX and a DVI printer program installed, you can typeset
+and print this manual. First switch to the the `gdb' subdirectory of
+the main source directory (for example, to `gdb-4.7/gdb') and then type:
make gdb.dvi
+
Installing GDB
-==============
+***************
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.
+program.
- The GDB distribution includes all the source code you need for GDB
-in a single directory, whose name is usually composed by appending the
+ The GDB distribution includes all the source code you need for GDB in
+a single directory, whose name is usually composed by appending the
version number to `gdb'.
- For example, the GDB version 4.4 distribution is in the `gdb-4.4'
+ For example, the GDB version 4.7 distribution is in the `gdb-4.7'
directory. That directory contains:
-`gdb-4.4/configure (and supporting files)'
+`gdb-4.7/configure (and supporting files)'
script for configuring GDB and all its supporting libraries.
-`gdb-4.4/gdb'
+`gdb-4.7/gdb'
the source specific to GDB itself
-`gdb-4.4/bfd'
- source for the Binary File Descriptor Library
+`gdb-4.7/bfd'
+ source for the Binary File Descriptor library
-`gdb-4.4/include'
+`gdb-4.7/include'
GNU include files
-`gdb-4.4/libiberty'
+`gdb-4.7/libiberty'
source for the `-liberty' free software library
-`gdb-4.4/readline'
+`gdb-4.7/opcodes'
+ source for the library of opcode tables and disassemblers
+
+`gdb-4.7/readline'
source for the GNU command-line interface
+`gdb-4.7/glob'
+ source for the GNU filename pattern-matching subroutine
+
+`gdb-4.7/mmalloc'
+ source for the GNU memory-mapped malloc package
+
The simplest way to configure and build GDB is to run `configure'
from the `gdb-VERSION-NUMBER' source directory, which in this example
-is the `gdb-4.4' directory.
+is the `gdb-4.7' directory.
- First switch to the `gdb-VERSION-NUMBER' source directory if you
-are not already in it; then run `configure'. Pass the identifier for
-the platform on which GDB will run as an argument.
+ First switch to the `gdb-VERSION-NUMBER' source directory if you are
+not already in it; then run `configure'. Pass the identifier for the
+platform on which GDB will run as an argument.
For example:
- cd gdb-4.4
+ cd gdb-4.7
./configure HOST
make
where HOST is an identifier such as `sun4' or `decstation', that
identifies the platform where GDB will run.
- These `configure' and `make' commands build the three libraries `bfd',
-`readline', and `libiberty', then `gdb' itself. The configured source
-files, and the binaries, are left in the corresponding source
-directories.
+ Running `configure HOST' followed by `make' builds the `bfd',
+`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
+The configured source files, and the binaries, are left in the
+corresponding source directories.
`configure' is a Bourne-shell (`/bin/sh') script; if your system
does not recognize this automatically when you run a different shell,
sh configure HOST
If you run `configure' from a directory that contains source
-directories for multiple libraries or programs, such as the `gdb-4.4'
-source directory for version 4.4, `configure' creates configuration
+directories for multiple libraries or programs, such as the `gdb-4.7'
+source directory for version 4.7, `configure' creates configuration
files for every directory level underneath (unless you tell it not to,
with the `--norecursion' option).
You can run the `configure' script from any of the subordinate
-directories in the GDB distribution, if you only want to configure
-that subdirectory; but be sure to specify a path to it.
+directories in the GDB distribution, if you only want to configure that
+subdirectory; but be sure to specify a path to it.
- For example, with version 4.4, type the following to configure only
+ For example, with version 4.7, type the following to configure only
the `bfd' subdirectory:
- cd gdb-4.4/bfd
+ cd gdb-4.7/bfd
../configure HOST
- You can install `gdb' anywhere; it has no hardwired paths.
-However, you should make sure that the shell on your path (named by
-the `SHELL' environment variable) is publicly readable. Remember that
-GDB uses the shell to start your program--some systems refuse to let
-GDB debug child processes whose programs are not readable.
+ You can install `gdb' anywhere; it has no hardwired paths. However,
+you should make sure that the shell on your path (named by the `SHELL'
+environment variable) is publicly readable. Remember that GDB uses the
+shell to start your program--some systems refuse to let GDB debug child
+processes whose programs are not readable.
Compiling GDB in Another Directory
-==================================
+===================================
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, rather than
-in the source directory. If your `make' program handles the `VPATH'
+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, rather than in
+the source directory. 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.
To build `gdb' in a separate directory, run `configure' with the
-`--srcdir' option to specify where to find the source. (Remember,
-you'll also need to specify a path to find `configure' itself from
-your working directory.)
+`--srcdir' option to specify where to find the source. (You'll also
+need to specify a path to find `configure' itself from your working
+directory. If the path to `configure' would be the same as the
+argument to `--srcdir', you can leave out the `--srcdir' option; it
+will be assumed.)
- For example, with version 4.4, you can build GDB in a separate
+ For example, with version 4.7, you can build GDB in a separate
directory for a Sun 4 like this:
- cd gdb-4.4
+ cd gdb-4.7
mkdir ../gdb-sun4
cd ../gdb-sun4
- ../gdb-4.4/configure --srcdir=../gdb-4.4 sun4
+ ../gdb-4.7/configure sun4
make
When `configure' builds a configuration using a remote source
the example, you'd find the Sun 4 library `libiberty.a' in the
directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
- One popular use for building several GDB configurations in separate
+ One popular reason to build several GDB configurations in separate
directories is to configure GDB for cross-compiling (where GDB runs on
one machine--the host--while debugging programs that run on another
machine--the target). You specify a cross-debugging target by giving
The `Makefile' generated by `configure' for each source directory
also runs recursively. If you type `make' in a source directory such
-as `gdb-4.4' (or in a separate configured directory configured with
-`--srcdir=PATH/gdb-4.4'), you will build all the required libraries,
+as `gdb-4.7' (or in a separate configured directory configured with
+`--srcdir=PATH/gdb-4.7'), you will build all the required libraries,
then build GDB.
When you have multiple hosts or targets configured in separate
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
ARCHITECTURE-VENDOR-OS
- For example, you can use the alias `sun4' as a HOST argument or in
-a `+target=TARGET' option, but the equivalent full name is
+ For example, you can use the alias `sun4' as a HOST argument or in a
+`--target=TARGET' option, but the equivalent full name is
`sparc-sun-sunos4'.
- The following table shows all the architectures, hosts, and OS
-prefixes that `configure' recognizes in GDB version 4.4. Entries in
-the "OS prefix" column ending in a `*' may be followed by a release
-number.
-
-
- ARCHITECTURE VENDOR OS prefix
- ------------+--------------------------+---------------------------
- | |
- 580 | altos hp | aix* msdos*
- a29k | amd ibm | amigados newsos*
- alliant | amdahl intel | aout nindy*
- arm | aout isi | bout osf*
- c1 | apollo little | bsd* sco*
- c2 | att mips | coff sunos*
- cray2 | bcs motorola | ctix* svr4
- h8300 | bout ncr | dgux* sym*
- i386 | bull next | dynix* sysv*
- i860 | cbm nyu | ebmon ultrix*
- i960 | coff sco | esix* unicos*
- m68000 | convergent sequent | hds unos*
- m68k | convex sgi | hpux* uts
- m88k | cray sony | irix* v88r*
- mips | dec sun | isc* vms*
- ns32k | encore unicom | kern vxworks*
- pyramid | gould utek | mach*
- romp | hitachi wrs |
- rs6000 | |
- sparc | |
- tahoe | |
- tron | |
- vax | |
- xmp | |
- ymp | |
-
- *Warning:* `configure' can represent a very large number of
- combinations of architecture, vendor, and OS. There is by no
- means support available for all possible combinations!
-
The `configure' script accompanying GDB 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
you can use it to test your guesses on abbreviations--for example:
% sh config.sub sun4
- sparc-sun-sunos4
+ sparc-sun-sunos411
% sh config.sub sun3
- m68k-sun-sunos4
+ m68k-sun-sunos411
% sh config.sub decstation
- mips-dec-ultrix
+ mips-dec-ultrix42
% sh config.sub hp300bsd
m68k-hp-bsd
% sh config.sub i386v
- i386-none-sysv
- % sh config.sub i486v
- *** Configuration "i486v" not recognized
+ i386-unknown-sysv
+ % sh config.sub i786v
+ Invalid configuration `i786v': machine `i786v' not recognized
`config.sub' is also distributed in the GDB source directory
-(`gdb-4.4', for version 4.4).
+(`gdb-4.7', for version 4.7).
`configure' Options
-===================
+====================
- Here is a summary of all the `configure' options and arguments that
-you might use for building GDB:
+ Here is a summary of the `configure' options and arguments that are
+most often useful for building GDB. `configure' also has several other
+options not listed here. *note : (configure.info)What Configure Does,
+for a full explanation of `configure'.
- configure [--destdir=DIR] [--srcdir=PATH]
+ configure [--help]
+ [--prefix=DIR]
+ [--srcdir=PATH]
[--norecursion] [--rm]
[--target=TARGET] HOST
You may introduce options with a single `-' rather than `--' if 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'.
+`--help'
+ Display a quick summary of how to invoke `configure'.
+
+`-prefix=DIR'
+ Configure the source to install programs and files under directory
+ `DIR'.
`--srcdir=PATH'
+ *Warning: using this option requires GNU `make', or another `make'
+ that implements the `VPATH' feature.*
Use this option to make configurations in directories separate
from the GDB source directories. Among other things, you can use
- this to build (or maintain) several configurations
- simultaneously, in separate directories. `configure' writes
- configuration specific files in the current directory, but
- arranges for them to use the source in the directory PATH.
- `configure' will create directories under the working directory
- in parallel to the source directories below PATH.
+ this to build (or maintain) several configurations simultaneously,
+ in separate directories. `configure' writes configuration
+ specific files in the current directory, but arranges for them to
+ use the source in the directory PATH. `configure' will create
+ directories under the working directory in parallel to the source
+ directories below PATH.
`--norecursion'
Configure only the directory level where `configure' is executed;
Remove the configuration that the other arguments specify.
`--target=TARGET'
- Configure GDB for cross-debugging programs running on the
- specified TARGET. Without this option, GDB is configured to debug
- programs that run on the same machine (HOST) as GDB itself.
+ Configure GDB for cross-debugging programs running on the specified
+ TARGET. 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.
hosts.
`configure' accepts other options, for compatibility with configuring
-other GNU tools recursively; but these are the only options that
-affect GDB or its supporting libraries.
+other GNU tools recursively; but these are the only options that affect
+GDB or its supporting libraries.
+
- Languages other than C
+Languages other than C
+=======================
GDB provides some support for debugging C++ progams. Partial Modula-2
support is now in GDB. GDB should work with FORTRAN programs. (If you
or nested functions will not currently work.
- Kernel debugging
+Kernel debugging
+=================
I have't done this myself so I can't really offer any advice.
Remote debugging over serial lines works fine, but the kernel debugging
-code in here has not been tested in years. Van Jacobson claims to have
-better kernel debugging.
+code in here has not been tested in years. Van Jacobson has
+better kernel debugging, but the UC lawyers won't let FSF have it.
- Remote debugging
+Remote debugging
+=================
-The files m68k-stub.c and i386-stub.c contain two examples of remote
-stubs to be used with remote.c. They are designeded to run standalone
-on a 68k or 386 cpu and communicate properly with the remote.c stub
-over a serial line.
+The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples of
+remote stubs to be used with remote.c. They are designed to run
+standalone on a 68k, 386, or SPARC cpu and communicate properly with
+the remote.c stub over a serial line.
The file rem-multi.shar contains a general stub that can probably
run on various different flavors of unix to allow debugging over a
Some working remote interfaces for talking to existing ROM monitors
are:
remote-eb.c AMD 29000 "EBMON"
+ remote-hms.c Hitachi Micro Systems H8/300 monitor
remote-nindy.c Intel 960 "Nindy"
remote-adapt.c AMD 29000 "Adapt"
remote-mm.c AMD 29000 "minimon"
via-ethernet back ends.
- Reporting Bugs
+Reporting Bugs
+===============
The correct address for reporting bugs found in gdb is
"bug-gdb@prep.ai.mit.edu". Please email all bugs to that address.
-Please include the GDB version number (e.g. gdb-4.4), and how
+Please include the GDB version number (e.g. gdb-4.7), and how
you configured it (e.g. "sun4" or "mach386 host, i586-intel-synopsys
target").
If you port gdb to a new machine, please send the required changes to
bug-gdb@prep.ai.mit.edu. There's lots of information about doing your
-own port in the file gdb-4.4/gdb/doc/gdbint.texinfo, which you can
+own port in the file gdb-4.7/gdb/doc/gdbint.texinfo, which you can
print out, or read with `info' (see the Makefile.in there). If your
changes are more than a few lines, obtain and send in a copyright
assignment from gnu@prep.ai.mit.edu, as described in the section
-`Writing Code for GDB'.
+`Writing Code for GDB' below.
- X Windows versus GDB
+X Windows versus GDB
+=====================
xgdb is obsolete. We are not doing any development or support of it.
(Try typing M-x gdb RETURN). Comments on this mode are welcome.
- Writing Code for GDB
+Writing Code for GDB
+=====================
+
+Documentation about GDB's internals is in the subdirectory doc, as
+`gdbint.texinfo'. In particular, there is a `cookbook' there on how
+to port GDB to a new machine. You can read it by hand, print it
+by using TeX and texinfo, or process it into an `info' file for use
+with Emacs' info mode or the standalone `info' program.
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
in a header file (e.g. #ifdef TIOCSETP), *please* make sure that you
have #include'd the relevant header file in that module!
+There is a list of all known `feature-test macros' in gdbint.texinfo.
+Each such macro should be defined (or left undefined) in a host-dependent,
+target-dependent, or native-dependent include file. Not all of the
+macros are cleanly separated this way, yet. As you make changes, move
+the code toward cleanliness.
+
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,
and exec_file_command.
- Debugging gdb with itself
+Debugging gdb with itself
+==========================
If gdb is limping on your machine, this is the preferred way to get it
fully functional. Be warned that in some ancient Unix systems, like
projects / binutils-gdb.git / commitdiff