1 README for gdb-4.18 release
2 Updated 4 Apr 1999 by Jim Blandy
4 This is GDB, the GNU source-level debugger.
5 A summary of new features is in the file `NEWS'.
7 See the GDB home page at http://www.cygnus.com/gdb/ for up to date
8 release information, mailing list links and archives, etc.
11 Unpacking and Installation -- quick overview
12 ==========================
14 In this release, the GDB debugger sources, the generic GNU include
15 files, the BFD ("binary file description") library, the readline
16 library, and other libraries all have directories of their own
17 underneath the gdb-4.18 directory. The idea is that a variety of GNU
18 tools can share a common copy of these things. Be aware of variation
19 over time--for example don't try to build gdb with a copy of bfd from
20 a release other than the gdb release (such as a binutils or gas
21 release), especially if the releases are more than a few weeks apart.
22 Configuration scripts and makefiles exist to cruise up and down this
23 directory tree and automatically build all the pieces in the right
26 When you unpack the gdb-4.18.tar.gz file, you'll find a directory
27 called `gdb-4.18', which contains:
29 COPYING config.sub* libiberty/ opcodes/
30 COPYING.LIB configure* mmalloc/ readline/
31 Makefile.in configure.in move-if-change* sim/
32 README etc/ mpw-README texinfo/
33 bfd/ gdb/ mpw-build.in utils/
34 config/ include/ mpw-config.in
35 config.guess* install.sh* mpw-configure
37 To build GDB, you can just do:
42 cp gdb/gdb /usr/local/bin/gdb (or wherever you want)
44 This will configure and build all the libraries as well as GDB.
45 If `configure' can't determine your system type, specify one as its
46 argument, e.g., sun4 or decstation.
48 If you get compiler warnings during this stage, see the `Reporting Bugs'
49 section below; there are a few known problems.
51 GDB requires an ANSI C compiler. If you do not have an ANSI C
52 compiler for your system, you may be able to download and install the
53 GNU CC compiler. It is available via anonymous FTP from ftp.gnu.org,
54 in /pub/gnu/gcc (as a URL, that's ftp://ftp.gnu.org/pub/gnu/gcc).
56 GDB can be used as a cross-debugger, running on a machine of one type
57 while debugging a program running on a machine of another type. See below.
63 All the documentation for GDB comes as part of the machine-readable
64 distribution. The documentation is written in Texinfo format, which is
65 a documentation system that uses a single source file to produce both
66 on-line information and a printed manual. You can use one of the Info
67 formatting commands to create the on-line version of the documentation
68 and TeX (or `texi2roff') to typeset the printed version.
70 GDB includes an already formatted copy of the on-line Info version of
71 this manual in the `gdb/doc' subdirectory. The main Info file is
72 `gdb-4.18/gdb/doc/gdb.info', and it refers to subordinate files matching
73 `gdb.info*' in the same directory. If necessary, you can print out
74 these files, or read them with any editor; but they are easier to read
75 using the `info' subsystem in GNU Emacs or the standalone `info' program,
76 available as part of the GNU Texinfo distribution.
78 If you want to format these Info files yourself, you need one of the
79 Info formatting programs, such as `texinfo-format-buffer' or
82 If you have `makeinfo' installed, and are in the top level GDB
83 source directory (`gdb-4.18', in the case of version 4.18), you can make
84 the Info file by typing:
89 If you want to typeset and print copies of this manual, you need
90 TeX, a program to print its DVI output files, and `texinfo.tex', the
91 Texinfo definitions file. This file is included in the GDB
92 distribution, in the directory `gdb-4.18/texinfo'.
94 TeX is a typesetting program; it does not print files directly, but
95 produces output files called DVI files. To print a typeset document,
96 you need a program to print DVI files. If your system has TeX
97 installed, chances are it has such a program. The precise command to
98 use depends on your system; `lpr -d' is common; another (for PostScript
99 devices) is `dvips'. The DVI print command may require a file name
100 without any extension or a `.dvi' extension.
102 TeX also requires a macro definitions file called `texinfo.tex'.
103 This file tells TeX how to typeset a document written in Texinfo
104 format. On its own, TeX cannot read, much less typeset a Texinfo file.
105 `texinfo.tex' is distributed with GDB and is located in the
106 `gdb-4.18/texinfo' directory.
108 If you have TeX and a DVI printer program installed, you can typeset
109 and print this manual. First switch to the the `gdb' subdirectory of
110 the main source directory (for example, to `gdb-4.18/gdb') and then type:
118 GDB comes with a `configure' script that automates the process of
119 preparing GDB for installation; you can then use `make' to build the
122 The GDB distribution includes all the source code you need for GDB in
123 a single directory, whose name is usually composed by appending the
124 version number to `gdb'.
126 For example, the GDB version 4.18 distribution is in the `gdb-4.18'
127 directory. That directory contains:
129 `gdb-4.18/{COPYING,COPYING.LIB}'
130 Standard GNU license files. Please read them.
133 source for the Binary File Descriptor library
136 script for configuring GDB, along with other support files
139 the source specific to GDB itself
145 source for the `-liberty' free software library
148 source for the GNU memory-mapped malloc package
151 source for the library of opcode tables and disassemblers
154 source for the GNU command-line interface
157 source for some simulators (ARM, D10V, SPARC, M32R, MIPS, PPC, V850, etc)
160 source for the GNU gettext library, for internationalization.
161 This is slightly modified from the standalone gettext
162 distribution you can get from GNU.
165 The `texinfo.tex' file, which you need in order to make a printed
169 Coding standards, useful files for editing GDB, and other
173 A grab bag of random utilities.
176 The simplest way to configure and build GDB is to run `configure'
177 from the `gdb-VERSION-NUMBER' source directory, which in this example
178 is the `gdb-4.18' directory.
180 First switch to the `gdb-VERSION-NUMBER' source directory if you are
181 not already in it; then run `configure'.
189 Running `configure' followed by `make' builds the `bfd',
190 `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
191 The configured source files, and the binaries, are left in the
192 corresponding source directories.
194 `configure' is a Bourne-shell (`/bin/sh') script; if your system
195 does not recognize this automatically when you run a different shell,
196 you may need to run `sh' on it explicitly:
200 If you run `configure' from a directory that contains source
201 directories for multiple libraries or programs, such as the `gdb-4.18'
202 source directory for version 4.18, `configure' creates configuration
203 files for every directory level underneath (unless you tell it not to,
204 with the `--norecursion' option).
206 You can run the `configure' script from any of the subordinate
207 directories in the GDB distribution, if you only want to configure that
208 subdirectory; but be sure to specify a path to it.
210 For example, with version 4.18, type the following to configure only
211 the `bfd' subdirectory:
216 You can install `gdb' anywhere; it has no hardwired paths. However,
217 you should make sure that the shell on your path (named by the `SHELL'
218 environment variable) is publicly readable. Remember that GDB uses the
219 shell to start your program--some systems refuse to let GDB debug child
220 processes whose programs are not readable.
223 Compiling GDB in another directory
224 ==================================
226 If you want to run GDB versions for several host or target machines,
227 you need a different `gdb' compiled for each combination of host and
228 target. `configure' is designed to make this easy by allowing you to
229 generate each configuration in a separate subdirectory, rather than in
230 the source directory. If your `make' program handles the `VPATH'
231 feature correctly (GNU `make' and SunOS 'make' are two that should),
232 running `make' in each of these directories builds the `gdb' program
235 To build `gdb' in a separate directory, run `configure' with the
236 `--srcdir' option to specify where to find the source. (You also need
237 to specify a path to find `configure' itself from your working
238 directory. If the path to `configure' would be the same as the
239 argument to `--srcdir', you can leave out the `--srcdir' option; it
242 For example, with version 4.18, you can build GDB in a separate
243 directory for a Sun 4 like this:
248 ../gdb-4.18/configure sun4
251 When `configure' builds a configuration using a remote source
252 directory, it creates a tree for the binaries with the same structure
253 (and using the same names) as the tree under the source directory. In
254 the example, you'd find the Sun 4 library `libiberty.a' in the
255 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
257 One popular reason to build several GDB configurations in separate
258 directories is to configure GDB for cross-compiling (where GDB runs on
259 one machine--the host--while debugging programs that run on another
260 machine--the target). You specify a cross-debugging target by giving
261 the `--target=TARGET' option to `configure'.
263 When you run `make' to build a program or library, you must run it
264 in a configured directory--whatever directory you were in when you
265 called `configure' (or one of its subdirectories).
267 The `Makefile' that `configure' generates in each source directory
268 also runs recursively. If you type `make' in a source directory such
269 as `gdb-4.18' (or in a separate configured directory configured with
270 `--srcdir=PATH/gdb-4.18'), you will build all the required libraries,
273 When you have multiple hosts or targets configured in separate
274 directories, you can run `make' on them in parallel (for example, if
275 they are NFS-mounted on each of the hosts); they will not interfere
279 Specifying names for hosts and targets
280 ======================================
282 The specifications used for hosts and targets in the `configure'
283 script are based on a three-part naming scheme, but some short
284 predefined aliases are also supported. The full naming scheme encodes
285 three pieces of information in the following pattern:
287 ARCHITECTURE-VENDOR-OS
289 For example, you can use the alias `sun4' as a HOST argument or in a
290 `--target=TARGET' option. The equivalent full name is
293 The `configure' script accompanying GDB does not provide any query
294 facility to list all supported host and target names or aliases.
295 `configure' calls the Bourne shell script `config.sub' to map
296 abbreviations to full names; you can read the script, if you wish, or
297 you can use it to test your guesses on abbreviations--for example:
303 % sh config.sub decstation
305 % sh config.sub hp300bsd
307 % sh config.sub i386v
309 % sh config.sub i786v
310 Invalid configuration `i786v': machine `i786v' not recognized
312 `config.sub' is also distributed in the GDB source directory
313 (`gdb-4.18', for version 4.18).
319 Here is a summary of the `configure' options and arguments that are
320 most often useful for building GDB. `configure' also has several other
321 options not listed here. *note : (configure.info)What Configure Does,
322 for a full explanation of `configure'.
327 [--norecursion] [--rm]
328 [--enable-build-warnings]
333 You may introduce options with a single `-' rather than `--' if you
334 prefer; but you may abbreviate option names if you use `--'.
337 Display a quick summary of how to invoke `configure'.
340 Configure the source to install programs and files under directory
344 *Warning: using this option requires GNU `make', or another `make'
345 that compatibly implements the `VPATH' feature.*
346 Use this option to make configurations in directories separate
347 from the GDB source directories. Among other things, you can use
348 this to build (or maintain) several configurations simultaneously,
349 in separate directories. `configure' writes configuration
350 specific files in the current directory, but arranges for them to
351 use the source in the directory PATH. `configure' will create
352 directories under the working directory in parallel to the source
353 directories below PATH.
356 Configure only the directory level where `configure' is executed;
357 do not propagate configuration to subdirectories.
360 Remove the configuration that the other arguments specify.
362 `--enable-build-warnings'
363 When building the GDB sources, ask the compiler to warn about any
364 code which looks even vaguely suspicious. You should only using
365 this feature if you're compiling with GNU CC. It passes the
371 -Wmissing-declarations
374 Configure GDB for cross-debugging programs running on the specified
375 TARGET. Without this option, GDB is configured to debug programs
376 that run on the same machine (HOST) as GDB itself.
378 There is no convenient way to generate a list of all available
382 Configure GDB to run on the specified HOST.
384 There is no convenient way to generate a list of all available
388 Same as `--host=HOST'. If you omit this, GDB will guess; it's
391 `configure' accepts other options, for compatibility with configuring
392 other GNU tools recursively; but these are the only options that affect
393 GDB or its supporting libraries.
396 Languages other than C
397 =======================
399 See the GDB manual (gdb/doc/gdb.texinfo) for information on this.
405 I have't done this myself so I can't really offer any advice.
406 Remote debugging over serial lines works fine, but the kernel debugging
407 code in here has not been tested in years. Van Jacobson has
408 better kernel debugging, but the UC lawyers won't let FSF have it.
414 The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples of
415 remote stubs to be used with remote.c. They are designed to run
416 standalone on an m68k, i386, or SPARC cpu and communicate properly with
417 the remote.c stub over a serial line.
419 The directory gdb/gdbserver/ contains `gdbserver', a program that
420 allows remote debugging for Unix applications. gdbserver is only
421 supported for some native configurations, including Sun 3, Sun 4,
424 There are a number of remote interfaces for talking to existing ROM
425 monitors and other hardware:
427 remote-adapt.c AMD 29000 "Adapt"
428 remote-array.c Array Tech RAID controller
429 remote-bug.c Motorola BUG monitor
430 remote-d10v.c GDB protocol, talking to a d10v chip
431 remote-e7000.c Hitachi E7000 ICE
432 remote-eb.c AMD 29000 "EBMON"
433 remote-es.c Ericsson 1800 monitor
434 remote-est.c EST emulator
435 remote-hms.c Hitachi Micro Systems H8/300 monitor
436 remote-mips.c MIPS remote debugging protocol
437 remote-mm.c AMD 29000 "minimon"
438 remote-nindy.c Intel 960 "Nindy"
439 remote-nrom.c NetROM ROM emulator
440 remote-os9k.c PC running OS/9000
441 remote-rdi.c ARM with Angel monitor
442 remote-rdp.c ARM with Demon monitor
443 remote-sds.c PowerPC SDS monitor
444 remote-sim.c Generalized simulator protocol
445 remote-st.c Tandem ST-2000 monitor
446 remote-udi.c AMD 29000 using the AMD "Universal Debug Interface"
447 remote-vx.c VxWorks realtime kernel
449 Remote-vx.c and the vx-share subdirectory contain a remote interface for the
450 VxWorks realtime kernel, which communicates over TCP using the Sun
451 RPC library. This would be a useful starting point for other remote-
452 via-ethernet back ends.
454 Remote-udi.c and the 29k-share subdirectory contain a remote interface
455 for AMD 29000 programs, which uses the AMD "Universal Debug Interface".
456 This allows GDB to talk to software simulators, emulators, and/or bare
457 hardware boards, via network or serial interfaces. Note that GDB only
458 provides an interface that speaks UDI, not a complete solution. You
459 will need something on the other end that also speaks UDI.
465 The correct address for reporting bugs found in gdb is
466 "bug-gdb@gnu.org". Please email all bugs, and all requests for
467 help with GDB, to that address. Please include the GDB version number
468 (e.g., gdb-4.18), and how you configured it (e.g., "sun4" or "mach386
469 host, i586-intel-synopsys target"). Since GDB now supports so many
470 different configurations, it is important that you be precise about this.
471 If at all possible, you should include the actual banner that GDB prints
472 when it starts up, or failing that, the actual configure command that
473 you used when configuring GDB.
475 For more information on how/whether to report bugs, see the GDB Bugs
476 section of the GDB manual (gdb/doc/gdb.texinfo).
480 * Under Ultrix 4.2 (DECstation-3100) or Alphas under OSF/1, we have
481 seen problems with backtraces after interrupting the inferior out
482 of a read(). The problem is caused by ptrace() returning an
483 incorrect value for the frame pointer register (register 15 or
484 30). As far as we can tell, this is a kernel problem. Any help
485 with this would be greatly appreciated.
487 * Under Ultrix 4.4 (DECstation-3100), setting the TERMCAP environment
488 variable to a string without a trailing ':' can cause GDB to dump
489 core upon startup. Although the core file makes it look as though
490 GDB code failed, the crash actually occurs within a call to the
491 termcap library function tgetent(). The problem can be solved by
492 using the GNU Termcap library.
494 Alphas running OSF/1 (versions 1.0 through 2.1) have the same buggy
495 termcap code, but GDB behaves strangely rather than crashing.
497 * On DECstations there are warnings about shift counts out of range in
498 various BFD modules. None of them is a cause for alarm, they are actually
499 a result of bugs in the DECstation compiler.
501 * Notes for the DEC Alpha using OSF/1:
502 The debugging output of native cc has two known problems; we view these
504 The linker miscompacts symbol tables, which causes gdb to confuse the
505 type of variables or results in `struct <illegal>' type outputs.
506 dbx has the same problems with those executables. A workaround is to
507 specify -Wl,-b when linking, but that will increase the executable size
509 If a structure has incomplete type in one file (e.g., "struct foo *"
510 without a definition for "struct foo"), gdb will be unable to find the
511 structure definition from another file.
512 It has been reported that the Ultrix 4.3A compiler on decstations has the
515 * Notes for Solaris 2.x, using the SPARCworks cc compiler:
516 You have to compile your program with the -xs option of the SPARCworks
517 compiler to be able to debug your program with gdb.
518 Under Solaris 2.3 you also need patch 101409-03 (Jumbo linker patch).
519 Under Solaris 2.2, if you have patch 101052 installed, make sure
520 that it is at least at revision 101052-06.
522 * Under Irix 5 for SGIs, you must have installed the `compiler_dev.hdr'
523 subsystem that is on the IDO CD, otherwise you will get complaints
524 that certain files such as `/usr/include/syms.h' cannot be found.
527 To compile gdb-4.18 on BSD/386, you must run the configure script and
528 its subscripts with bash. Here is an easy way to do this:
530 bash -c 'CONFIG_SHELL=/bin/bash ./configure'
532 (configure will report i386-unknown-bsd). Then, compile with the
533 standard "make" command.
535 GDB can produce warnings about symbols that it does not understand. By
536 default, these warnings are disabled. You can enable them by executing
537 `set complaint 10' (which you can put in your ~/.gdbinit if you like).
538 I recommend doing this if you are working on a compiler, assembler,
539 linker, or GDB, since it will point out problems that you may be able
540 to fix. Warnings produced during symbol reading indicate some mismatch
541 between the object file and GDB's symbol reading code. In many cases,
542 it's a mismatch between the specs for the object file format, and what
543 the compiler actually outputs or the debugger actually understands.
547 =====================
549 You should check out DDD, the Data Display Debugger. Here's the blurb
550 from the DDD web site, http://www.cs.tu-bs.de/softech/ddd:
552 The Data Display Debugger (DDD) is a popular graphical user
553 interface for command-line debuggers such as GDB, DBX, JDB, WDB,
554 XDB, the Perl debugger, and the Python debugger. Besides ``usual''
555 front-end features such as viewing source texts, DDD has become
556 famous through its interactive graphical data display, where data
557 structures are displayed as graphs. A simple mouse click
558 dereferences pointers or views structure contents, updated each
559 time the program stops. Using DDD, you can reason about your
560 application by watching its data, not just by viewing it execute
561 lines of source code.
563 Emacs users will very likely enjoy the Grand Unified Debugger mode;
564 try typing `M-x gdb RET'.
566 Those interested in experimenting with a new kind of gdb-mode
567 should load gdb/gdba.el into GNU Emacs 19.25 or later. Comments
568 on this mode are also welcome.
572 =====================
574 There is a lot of information about writing code for GDB in the
575 internals manual, distributed with GDB in gdb/doc/gdbint.texinfo. You
576 can read it by hand, print it by using TeX and texinfo, or process it
577 into an `info' file for use with Emacs' info mode or the standalone
580 If you are pondering writing anything but a short patch, especially
581 take note of the information about copyrights in the node Submitting
582 Patches. It can take quite a while to get all the paperwork done, so
583 we encourage you to start that process as soon as you decide you are
584 planning to work on something, or at least well ahead of when you
585 think you will be ready to submit the patches.
591 There is a DejaGNU based testsuite available for testing your newly
592 built GDB, or for regression testing GDBs with local modifications.
594 Running the testsuite requires the prior installation of DejaGNU,
595 which is generally available via ftp; you'll need a pretty recent
596 release. Once DejaGNU is installed, you can run the tests in one of
599 (1) cd gdb-4.18/gdb (assuming you also unpacked gdb)
604 (2) cd gdb-4.18/gdb/testsuite
605 make site.exp (builds the site specific file)
606 runtest -tool gdb GDB=../gdb (or GDB=<somepath> as appropriate)
608 The second method gives you slightly more control in case of problems with
609 building one or more test executables or if you are using the testsuite
610 'standalone', without it being part of the GDB source tree.
612 See the DejaGNU documentation for further details.
615 (this is for editing this file with GNU emacs)
projects / thirdparty / binutils-gdb.git / blob