FreeChainXenon/binutils-gdb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update README.

Browse source
This commit is contained in:
John Gilmore 1991-08-24 00:15:18 +00:00
parent ce97f9130a
commit 846058edd8
1 changed files with 265 additions and 142 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

407
gdb/README
View file

@ -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
More Documentation
==================
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,
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.
make gdb.dvi
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.
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.
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
to format the text of this manual, and print it with the usual output
method for TeX DVI files at your site.
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
cd gdb-4.0/gdb
make refcard.dvi
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
============================
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.
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:
`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 GNUSRC
./configure +f sun4
cd Host-sun4/Target-sun4
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 `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.
The `Makefile' in
gdb-4.0/Host-sparc-sun-sunos4/Target-i960-wrs-vxworks
will `cd' to the appropriate lower-level directories, for example:
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.
Specifying Names for Hosts and Targets
======================================
`configure' Options
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