- 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
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
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
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
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
projects / external / binutils.git / commitdiff