1 README for gdb-6.3 release
2 Updated 20, November, 2006
4 This is GDB, the GNU source-level debugger.
6 A summary of new features is in the file `gdb/NEWS'.
8 Check the GDB home page at http://www.gnu.org/software/gdb/ for up to
9 date release information, mailing list links and archives, etc.
11 The file `gdb/PROBLEMS' contains information on problems identified
12 late in the release cycle. GDB's bug tracking data base at
13 http://www.gnu.org/software/gdb/bugs/ contains a more complete list of
17 Unpacking and Installation -- quick overview
18 ==========================
20 In this release, the GDB debugger sources, the generic GNU include
21 files, the BFD ("binary file description") library, the readline
22 library, and other libraries all have directories of their own
23 underneath the gdb-6.3 directory. The idea is that a variety of GNU
24 tools can share a common copy of these things. Be aware of variation
25 over time--for example don't try to build GDB with a copy of bfd from
26 a release other than the GDB release (such as a binutils release),
27 especially if the releases are more than a few weeks apart.
28 Configuration scripts and makefiles exist to cruise up and down this
29 directory tree and automatically build all the pieces in the right
32 When you unpack the gdb-6.3.tar.gz file, you'll find a directory
33 called `gdb-6.3', which contains:
35 COPYING config-ml.in gettext.m4 ltconfig sim
36 COPYING.LIB config.guess include ltmain.sh src-release
37 Makefile.def config.sub install-sh md5.sum symlink-tree
38 Makefile.in configure libiberty missing texinfo
39 Makefile.tpl configure.in libtool.m4 mkinstalldirs ylwrap
40 README djunpack.bat ltcf-c.sh move-if-change
41 bfd etc ltcf-cxx.sh opcodes
42 config gdb ltcf-gcj.sh readline
44 You can build GDB right in the source directory:
49 cp gdb/gdb /usr/local/bin/gdb (or wherever you want)
51 However, we recommend that an empty directory be used instead.
52 This way you do not clutter your source tree with binary files
53 and will be able to create different builds with different
54 configuration options.
56 You can build GDB in any empty build directory:
60 <full path to your sources>/gdb-6.3/configure
62 cp gdb/gdb /usr/local/bin/gdb (or wherever you want)
64 (Building GDB with DJGPP tools for MS-DOS/MS-Windows is slightly
65 different; see the file gdb-6.3/gdb/config/djgpp/README for details.)
67 This will configure and build all the libraries as well as GDB. If
68 `configure' can't determine your system type, specify one as its
69 argument, e.g., `./configure sun4' or `./configure decstation'.
71 Make sure that your 'configure' line ends in 'gdb-6.3/configure':
73 /berman/migchain/source/gdb-6.3/configure # RIGHT
74 /berman/migchain/source/gdb-6.3/gdb/configure # WRONG
76 The GDB package contains several subdirectories, such as 'gdb',
77 'bfd', and 'readline'. If your 'configure' line ends in
78 'gdb-6.3/gdb/configure', then you are configuring only the gdb
79 subdirectory, not the whole GDB package. This leads to build errors
82 make: *** No rule to make target `../bfd/bfd.h', needed by `gdb.o'. Stop.
84 If you get other compiler errors during this stage, see the `Reporting
85 Bugs' section below; there are a few known problems.
87 GDB requires an ISO C (ANSI C) compiler. If you do not have an ISO
88 C compiler for your system, you may be able to download and install
89 the GNU CC compiler. It is available via anonymous FTP from the
90 directory `ftp://ftp.gnu.org/pub/gnu/gcc'. GDB also requires an ISO
91 C standard library. The GDB remote server, GDBserver, builds with some
92 non-ISO standard libraries - e.g. for Windows CE.
94 GDB uses Expat, an XML parsing library, to implement some target-specific
95 features. Expat will be linked in if it is available at build time, or
96 those features will be disabled. The latest version of Expat should be
97 available from `http://expat.sourceforge.net'.
99 GDB can be used as a cross-debugger, running on a machine of one
100 type while debugging a program running on a machine of another type.
107 All the documentation for GDB comes as part of the machine-readable
108 distribution. The documentation is written in Texinfo format, which
109 is a documentation system that uses a single source file to produce
110 both on-line information and a printed manual. You can use one of the
111 Info formatting commands to create the on-line version of the
112 documentation and TeX (or `texi2roff') to typeset the printed version.
114 GDB includes an already formatted copy of the on-line Info version
115 of this manual in the `gdb/doc' subdirectory. The main Info file is
116 `gdb-6.3/gdb/doc/gdb.info', and it refers to subordinate files
117 matching `gdb.info*' in the same directory. If necessary, you can
118 print out these files, or read them with any editor; but they are
119 easier to read using the `info' subsystem in GNU Emacs or the
120 standalone `info' program, available as part of the GNU Texinfo
123 If you want to format these Info files yourself, you need one of the
124 Info formatting programs, such as `texinfo-format-buffer' or
127 If you have `makeinfo' installed, and are in the top level GDB
128 source directory (`gdb-6.3', in the case of version 6.3), you can make
129 the Info file by typing:
134 If you want to typeset and print copies of this manual, you need
135 TeX, a program to print its DVI output files, and `texinfo.tex', the
136 Texinfo definitions file. This file is included in the GDB
137 distribution, in the directory `gdb-6.3/texinfo'.
139 TeX is a typesetting program; it does not print files directly, but
140 produces output files called DVI files. To print a typeset document,
141 you need a program to print DVI files. If your system has TeX
142 installed, chances are it has such a program. The precise command to
143 use depends on your system; `lpr -d' is common; another (for PostScript
144 devices) is `dvips'. The DVI print command may require a file name
145 without any extension or a `.dvi' extension.
147 TeX also requires a macro definitions file called `texinfo.tex'.
148 This file tells TeX how to typeset a document written in Texinfo
149 format. On its own, TeX cannot read, much less typeset a Texinfo file.
150 `texinfo.tex' is distributed with GDB and is located in the
151 `gdb-6.3/texinfo' directory.
153 If you have TeX and a DVI printer program installed, you can typeset
154 and print this manual. First switch to the the `gdb' subdirectory of
155 the main source directory (for example, to `gdb-6.3/gdb') and then type:
159 If you prefer to have the manual in PDF format, type this from the
160 `gdb/doc' subdirectory of the main source directory:
164 For this to work, you will need the PDFTeX package to be installed.
170 GDB comes with a `configure' script that automates the process of
171 preparing GDB for installation; you can then use `make' to build the
174 The GDB distribution includes all the source code you need for GDB in
175 a single directory, whose name is usually composed by appending the
176 version number to `gdb'.
178 For example, the GDB version 6.3 distribution is in the `gdb-6.3'
179 directory. That directory contains:
181 `gdb-6.3/{COPYING,COPYING.LIB}'
182 Standard GNU license files. Please read them.
185 source for the Binary File Descriptor library
188 script for configuring GDB, along with other support files
191 the source specific to GDB itself
197 source for the `-liberty' free software library
200 source for the library of opcode tables and disassemblers
203 source for the GNU command-line interface
204 NOTE: The readline library is compiled for use by GDB, but will
205 not be installed on your system when "make install" is issued.
208 source for some simulators (ARM, D10V, SPARC, M32R, MIPS, PPC, V850, etc)
211 The `texinfo.tex' file, which you need in order to make a printed
215 Coding standards, useful files for editing GDB, and other
218 Note: the following instructions are for building GDB on Unix or
219 Unix-like systems. Instructions for building with DJGPP for
220 MS-DOS/MS-Windows are in the file gdb/config/djgpp/README.
222 The simplest way to configure and build GDB is to run `configure'
223 from the `gdb-VERSION-NUMBER' source directory, which in this example
224 is the `gdb-6.3' directory.
226 First switch to the `gdb-VERSION-NUMBER' source directory if you are
227 not already in it; then run `configure'.
235 Running `configure' followed by `make' builds the `bfd',
236 `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
237 The configured source files, and the binaries, are left in the
238 corresponding source directories.
240 `configure' is a Bourne-shell (`/bin/sh') script; if your system
241 does not recognize this automatically when you run a different shell,
242 you may need to run `sh' on it explicitly:
246 If you run `configure' from a directory that contains source
247 directories for multiple libraries or programs, such as the `gdb-6.3'
248 source directory for version 6.3, `configure' creates configuration
249 files for every directory level underneath (unless you tell it not to,
250 with the `--norecursion' option).
252 You can run the `configure' script from any of the subordinate
253 directories in the GDB distribution, if you only want to configure that
254 subdirectory; but be sure to specify a path to it.
256 For example, with version 6.3, type the following to configure only
257 the `bfd' subdirectory:
262 You can install `gdb' anywhere; it has no hardwired paths. However,
263 you should make sure that the shell on your path (named by the `SHELL'
264 environment variable) is publicly readable. Remember that GDB uses the
265 shell to start your program--some systems refuse to let GDB debug child
266 processes whose programs are not readable.
269 Compiling GDB in another directory
270 ==================================
272 If you want to run GDB versions for several host or target machines,
273 you need a different `gdb' compiled for each combination of host and
274 target. `configure' is designed to make this easy by allowing you to
275 generate each configuration in a separate subdirectory, rather than in
276 the source directory. If your `make' program handles the `VPATH'
277 feature correctly (GNU `make' and SunOS 'make' are two that should),
278 running `make' in each of these directories builds the `gdb' program
281 To build `gdb' in a separate directory, run `configure' with the
282 `--srcdir' option to specify where to find the source. (You also need
283 to specify a path to find `configure' itself from your working
284 directory. If the path to `configure' would be the same as the
285 argument to `--srcdir', you can leave out the `--srcdir' option; it
288 For example, with version 6.3, you can build GDB in a separate
289 directory for a Sun 4 like this:
297 When `configure' builds a configuration using a remote source
298 directory, it creates a tree for the binaries with the same structure
299 (and using the same names) as the tree under the source directory. In
300 the example, you'd find the Sun 4 library `libiberty.a' in the
301 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
303 One popular reason to build several GDB configurations in separate
304 directories is to configure GDB for cross-compiling (where GDB runs on
305 one machine--the host--while debugging programs that run on another
306 machine--the target). You specify a cross-debugging target by giving
307 the `--target=TARGET' option to `configure'.
309 When you run `make' to build a program or library, you must run it
310 in a configured directory--whatever directory you were in when you
311 called `configure' (or one of its subdirectories).
313 The `Makefile' that `configure' generates in each source directory
314 also runs recursively. If you type `make' in a source directory such
315 as `gdb-6.3' (or in a separate configured directory configured with
316 `--srcdir=PATH/gdb-6.3'), you will build all the required libraries,
319 When you have multiple hosts or targets configured in separate
320 directories, you can run `make' on them in parallel (for example, if
321 they are NFS-mounted on each of the hosts); they will not interfere
325 Specifying names for hosts and targets
326 ======================================
328 The specifications used for hosts and targets in the `configure'
329 script are based on a three-part naming scheme, but some short
330 predefined aliases are also supported. The full naming scheme encodes
331 three pieces of information in the following pattern:
333 ARCHITECTURE-VENDOR-OS
335 For example, you can use the alias `sun4' as a HOST argument or in a
336 `--target=TARGET' option. The equivalent full name is
339 The `configure' script accompanying GDB does not provide any query
340 facility to list all supported host and target names or aliases.
341 `configure' calls the Bourne shell script `config.sub' to map
342 abbreviations to full names; you can read the script, if you wish, or
343 you can use it to test your guesses on abbreviations--for example:
349 % sh config.sub decstation
351 % sh config.sub hp300bsd
353 % sh config.sub i386v
355 % sh config.sub i786v
356 Invalid configuration `i786v': machine `i786v' not recognized
358 `config.sub' is also distributed in the GDB source directory
359 (`gdb-6.3', for version 6.3).
365 Here is a summary of the `configure' options and arguments that are
366 most often useful for building GDB. `configure' also has several other
367 options not listed here. *note : (configure.info)What Configure Does,
368 for a full explanation of `configure'.
373 [--norecursion] [--rm]
374 [--enable-build-warnings]
379 You may introduce options with a single `-' rather than `--' if you
380 prefer; but you may abbreviate option names if you use `--'.
383 Display a quick summary of how to invoke `configure'.
386 Configure the source to install programs and files under directory
390 *Warning: using this option requires GNU `make', or another `make'
391 that compatibly implements the `VPATH' feature.*
392 Use this option to make configurations in directories separate
393 from the GDB source directories. Among other things, you can use
394 this to build (or maintain) several configurations simultaneously,
395 in separate directories. `configure' writes configuration
396 specific files in the current directory, but arranges for them to
397 use the source in the directory PATH. `configure' will create
398 directories under the working directory in parallel to the source
399 directories below PATH.
402 Configure GDB to run on the specified HOST.
404 There is no convenient way to generate a list of all available
408 Same as `--host=HOST'. If you omit this, GDB will guess; it's
412 Configure only the directory level where `configure' is executed;
413 do not propagate configuration to subdirectories.
416 Remove the configuration that the other arguments specify.
418 `--enable-build-warnings'
419 When building the GDB sources, ask the compiler to warn about any
420 code which looks even vaguely suspicious. You should only using
421 this feature if you're compiling with GNU CC. It passes the
432 Treat compiler warnings as werrors. Use this only with GCC. It
433 adds the -Werror flag to the compiler, which will fail the
434 compilation if the compiler outputs any warning messages.
437 Configure GDB for cross-debugging programs running on the specified
438 TARGET. Without this option, GDB is configured to debug programs
439 that run on the same machine (HOST) as GDB itself.
441 There is no convenient way to generate a list of all available
444 `--with-gdb-datadir=PATH'
445 Set the GDB-specific data directory. GDB will look here for
446 certain supporting files or scripts. This defaults to the `gdb'
447 subdirectory of `datadir' (which can be set using `--datadir').
449 `--with-relocated-sources=DIR'
450 Sets up the default source path substitution rule so that
451 directory names recorded in debug information will be
452 automatically adjusted for any directory under DIR. DIR should
453 be a subdirectory of GDB's configured prefix, the one mentioned
454 in the `--prefix' or `--exec-prefix' options to configure. This
455 option is useful if GDB is supposed to be moved to a different
456 place after it is built.
458 `--enable-64-bit-bfd'
459 Enable 64-bit support in BFD on 32-bit hosts.
462 Build GDB without the GDB/MI machine interface.
465 Build GDB with the text-mode full-screen user interface (TUI).
466 Requires a curses library (ncurses and cursesX are also
470 Build GDB with the gdbtk GUI interface. Requires TCL/Tk to be
474 Use the libunwind library for unwinding function call stack. See
475 http://www.nongnu.org/libunwind/index.html fro details.
476 Supported only on some platforms.
479 Use the curses library instead of the termcap library, for
480 text-mode terminal operations.
482 `--enable-profiling' Enable profiling of GDB itself. Necessary if you
483 want to use the "maint set profile" command for profiling GDB.
484 Requires the functions `monstartup' and `_mcleanup' to be present
485 in the standard C library used to build GDB, and also requires a
486 compiler that supports the `-pg' option.
488 `--with-system-readline'
489 Use the readline library installed on the host, rather than the
490 library supplied as part of GDB tarball.
493 Build GDB with the libexpat library. (Done by default if
494 libexpat is installed and found at configure time.) This library
495 is used to read XML files supplied with GDB. If it is
496 unavailable, some features, such as remote protocol memory maps,
497 target descriptions, and shared library lists, that are based on
498 XML files, will not be available in GDB. If your host does not
499 have libexpat installed, you can get the latest version from
500 http://expat.sourceforge.net.
502 `--with-python[=PATH]'
503 Build GDB with Python scripting support. (Done by default if
504 libpython is present and found at configure time.) Python makes
505 GDB scripting much more powerful than the restricted CLI
506 scripting language. If your host does not have Python installed,
507 you can find it on http://www.python.org/download/. The oldest
508 version of Python supported by GDB is 2.4. The optional argument
509 PATH says where to find the Python headers and libraries; the
510 configure script will look in PATH/include for headers and in
511 PATH/lib for the libraries.
513 `--without-included-regex'
514 Don't use the regex library included with GDB (as part of the
515 libiberty library). This is the default on hosts with version 2
516 of the GNU C library.
519 Use DIR as the default system root directory for libraries whose
520 file names begin with `/lib' or `/usr/lib'. (The value of DIR
521 can be modified at run time by using the "set sysroot" command.)
522 If DIR is under the GDB configured prefix (set with `--prefix' or
523 `--exec-prefix' options), the default system root will be
524 automatically adjusted if and when GDB is moved to a different
527 `--with-system-gdbinit=FILE'
528 Configure GDB to automatically load a system-wide init file.
529 FILE should be an absolute file name. If FILE is in a directory
530 under the configured prefix, and GDB is moved to another location
531 after being built, the location of the system-wide init file will
532 be adjusted accordingly.
534 `configure' accepts other options, for compatibility with configuring
535 other GNU tools recursively; but these are the only options that affect
536 GDB or its supporting libraries.
542 The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples
543 of remote stubs to be used with remote.c. They are designed to run
544 standalone on an m68k, i386, or SPARC cpu and communicate properly
545 with the remote.c stub over a serial line.
547 The directory gdb/gdbserver/ contains `gdbserver', a program that
548 allows remote debugging for Unix applications. GDBserver is only
549 supported for some native configurations, including Sun 3, Sun 4, and
551 The file gdb/gdbserver/README includes further notes on GDBserver; in
552 particular, it explains how to build GDBserver for cross-debugging
553 (where GDBserver runs on the target machine, which is of a different
554 architecture than the host machine running GDB).
556 There are a number of remote interfaces for talking to existing ROM
557 monitors and other hardware:
559 remote-mips.c MIPS remote debugging protocol
560 remote-sds.c PowerPC SDS monitor
561 remote-sim.c Generalized simulator protocol
564 Reporting Bugs in GDB
565 =====================
567 There are several ways of reporting bugs in GDB. The prefered
568 method is to use the World Wide Web:
570 http://www.gnu.org/software/gdb/bugs/
572 As an alternative, the bug report can be submitted, via e-mail, to the
573 address "bug-gdb@gnu.org".
575 When submitting a bug, please include the GDB version number (e.g.,
576 gdb-6.3), and how you configured it (e.g., "sun4" or "mach386 host,
577 i586-intel-synopsys target"). Since GDB now supports so many
578 different configurations, it is important that you be precise about
579 this. If at all possible, you should include the actual banner that
580 GDB prints when it starts up, or failing that, the actual configure
581 command that you used when configuring GDB.
583 For more information on how/whether to report bugs, see the
584 Reporting Bugs chapter of the GDB manual (gdb/doc/gdb.texinfo).
587 Graphical interface to GDB -- X Windows, MS Windows
588 ==========================
590 Several graphical interfaces to GDB are available. You should
593 http://www.gnu.org/software/gdb/links/
595 for an up-to-date list.
597 Emacs users will very likely enjoy the Grand Unified Debugger mode;
598 try typing `M-x gdb RET'.
602 =====================
604 There is a lot of information about writing code for GDB in the
605 internals manual, distributed with GDB in gdb/doc/gdbint.texinfo. You
606 can read it by hand, print it by using TeX and texinfo, or process it
607 into an `info' file for use with Emacs' info mode or the standalone
610 If you are pondering writing anything but a short patch, especially
611 take note of the information about copyrights in the node Submitting
612 Patches. It can take quite a while to get all the paperwork done, so
613 we encourage you to start that process as soon as you decide you are
614 planning to work on something, or at least well ahead of when you
615 think you will be ready to submit the patches.
621 Included with the GDB distribution is a DejaGNU based testsuite
622 that can either be used to test your newly built GDB, or for
623 regression testing a GDB with local modifications.
625 Running the testsuite requires the prior installation of DejaGNU,
626 which is generally available via ftp. The directory
627 ftp://sources.redhat.com/pub/dejagnu/ will contain a recent snapshot.
628 Once DejaGNU is installed, you can run the tests in one of the
641 (3) cd gdb-6.3/gdb/testsuite
642 make site.exp (builds the site specific file)
643 runtest -tool gdb GDB=../gdb (or GDB=<somepath> as appropriate)
645 When using a `make'-based method, you can use the Makefile variable
646 `RUNTESTFLAGS' to pass flags to `runtest', e.g.:
648 make RUNTESTFLAGS=--directory=gdb.cp check
650 If you use GNU make, you can use its `-j' option to run the testsuite
651 in parallel. This can greatly reduce the amount of time it takes for
652 the testsuite to run. In this case, if you set `RUNTESTFLAGS' then,
653 by default, the tests will be run serially even under `-j'. You can
654 override this and force a parallel run by setting the `make' variable
655 `FORCE_PARALLEL' to any non-empty value. Note that the parallel `make
656 check' assumes that you want to run the entire testsuite, so it is not
657 compatible with some dejagnu options, like `--directory'.
659 The last method gives you slightly more control in case of problems
660 with building one or more test executables or if you are using the
661 testsuite `standalone', without it being part of the GDB source tree.
663 See the DejaGNU documentation for further details.
666 (this is for editing this file with GNU emacs)
projects / deliverable / binutils-gdb.git / blob