1 README for gdb-7.0 release 2 Updated 06, October, 2009 3 4This is GDB, the GNU source-level debugger. 5 6A summary of new features is in the file `gdb/NEWS'. 7 8Check the GDB home page at http://www.gnu.org/software/gdb/ for up to 9date release information, mailing list links and archives, etc. 10 11The file `gdb/PROBLEMS' contains information on problems identified 12late in the release cycle. GDB's bug tracking data base at 13http://www.gnu.org/software/gdb/bugs/ contains a more complete list of 14bugs. 15 16 17Unpacking and Installation -- quick overview 18========================== 19 20 In this release, the GDB debugger sources, the generic GNU include 21files, the BFD ("binary file description") library, the readline 22library, and other libraries all have directories of their own 23underneath the gdb-7.0 directory. The idea is that a variety of GNU 24tools can share a common copy of these things. Be aware of variation 25over time--for example don't try to build gdb with a copy of bfd from 26a release other than the gdb release (such as a binutils release), 27especially if the releases are more than a few weeks apart. 28Configuration scripts and makefiles exist to cruise up and down this 29directory tree and automatically build all the pieces in the right 30order. 31 32 When you unpack the gdb-7.0.tar.gz file, you'll find a directory 33called `gdb-7.0', which contains: 34 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 43 44You can build GDB right in the source directory: 45 46 cd gdb-7.0 47 ./configure 48 make 49 cp gdb/gdb /usr/local/bin/gdb (or wherever you want) 50 51However, we recommend that an empty directory be used instead. 52This way you do not clutter your source tree with binary files 53and will be able to create different builds with different 54configuration options. 55 56You can build GDB in any empty build directory: 57 58 mkdir build 59 cd build 60 <full path to your sources>/gdb-7.0/configure 61 make 62 cp gdb/gdb /usr/local/bin/gdb (or wherever you want) 63 64(Building GDB with DJGPP tools for MS-DOS/MS-Windows is slightly 65different; see the file gdb-7.0/gdb/config/djgpp/README for details.) 66 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 69argument, e.g., `./configure sun4' or `./configure decstation'. 70 71 Make sure that your 'configure' line ends in 'gdb-7.0/configure': 72 73 /berman/migchain/source/gdb-7.0/configure # RIGHT 74 /berman/migchain/source/gdb-7.0/gdb/configure # WRONG 75 76 The gdb package contains several subdirectories, such as 'gdb', 77'bfd', and 'readline'. If your 'configure' line ends in 78'gdb-7.0/gdb/configure', then you are configuring only the gdb 79subdirectory, not the whole gdb package. This leads to build errors 80such as: 81 82 make: *** No rule to make target `../bfd/bfd.h', needed by `gdb.o'. Stop. 83 84 If you get other compiler errors during this stage, see the `Reporting 85Bugs' section below; there are a few known problems. 86 87 GDB requires an ISO C (ANSI C) compiler. If you do not have an ISO 88C compiler for your system, you may be able to download and install 89the GNU CC compiler. It is available via anonymous FTP from the 90directory `ftp://ftp.gnu.org/pub/gnu/gcc'. GDB also requires an ISO 91C standard library. The GDB remote server, gdbserver, builds with some 92non-ISO standard libraries - e.g. for Windows CE. 93 94 GDB uses Expat, an XML parsing library, to implement some target-specific 95features. Expat will be linked in if it is available at build time, or 96those features will be disabled. The latest version of Expat should be 97available from `http://expat.sourceforge.net'. 98 99 GDB can be used as a cross-debugger, running on a machine of one 100type while debugging a program running on a machine of another type. 101See below. 102 103 104More Documentation 105****************** 106 107 All the documentation for GDB comes as part of the machine-readable 108distribution. The documentation is written in Texinfo format, which 109is a documentation system that uses a single source file to produce 110both on-line information and a printed manual. You can use one of the 111Info formatting commands to create the on-line version of the 112documentation and TeX (or `texi2roff') to typeset the printed version. 113 114 GDB includes an already formatted copy of the on-line Info version 115of this manual in the `gdb/doc' subdirectory. The main Info file is 116`gdb-7.0/gdb/doc/gdb.info', and it refers to subordinate files 117matching `gdb.info*' in the same directory. If necessary, you can 118print out these files, or read them with any editor; but they are 119easier to read using the `info' subsystem in GNU Emacs or the 120standalone `info' program, available as part of the GNU Texinfo 121distribution. 122 123 If you want to format these Info files yourself, you need one of the 124Info formatting programs, such as `texinfo-format-buffer' or 125`makeinfo'. 126 127 If you have `makeinfo' installed, and are in the top level GDB 128source directory (`gdb-7.0', in the case of version 7.0), you can make 129the Info file by typing: 130 131 cd gdb/doc 132 make info 133 134 If you want to typeset and print copies of this manual, you need 135TeX, a program to print its DVI output files, and `texinfo.tex', the 136Texinfo definitions file. This file is included in the GDB 137distribution, in the directory `gdb-7.0/texinfo'. 138 139 TeX is a typesetting program; it does not print files directly, but 140produces output files called DVI files. To print a typeset document, 141you need a program to print DVI files. If your system has TeX 142installed, chances are it has such a program. The precise command to 143use depends on your system; `lpr -d' is common; another (for PostScript 144devices) is `dvips'. The DVI print command may require a file name 145without any extension or a `.dvi' extension. 146 147 TeX also requires a macro definitions file called `texinfo.tex'. 148This file tells TeX how to typeset a document written in Texinfo 149format. 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-7.0/texinfo' directory. 152 153 If you have TeX and a DVI printer program installed, you can typeset 154and print this manual. First switch to the the `gdb' subdirectory of 155the main source directory (for example, to `gdb-7.0/gdb') and then type: 156 157 make doc/gdb.dvi 158 159 If you prefer to have the manual in PDF format, type this from the 160`gdb/doc' subdirectory of the main source directory: 161 162 make gdb.pdf 163 164For this to work, you will need the PDFTeX package to be installed. 165 166 167Installing GDB 168************** 169 170 GDB comes with a `configure' script that automates the process of 171preparing GDB for installation; you can then use `make' to build the 172`gdb' program. 173 174 The GDB distribution includes all the source code you need for GDB in 175a single directory, whose name is usually composed by appending the 176version number to `gdb'. 177 178 For example, the GDB version 7.0 distribution is in the `gdb-7.0' 179directory. That directory contains: 180 181`gdb-7.0/{COPYING,COPYING.LIB}' 182 Standard GNU license files. Please read them. 183 184`gdb-7.0/bfd' 185 source for the Binary File Descriptor library 186 187`gdb-7.0/config*' 188 script for configuring GDB, along with other support files 189 190`gdb-7.0/gdb' 191 the source specific to GDB itself 192 193`gdb-7.0/include' 194 GNU include files 195 196`gdb-7.0/libiberty' 197 source for the `-liberty' free software library 198 199`gdb-7.0/opcodes' 200 source for the library of opcode tables and disassemblers 201 202`gdb-7.0/readline' 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. 206 207`gdb-7.0/sim' 208 source for some simulators (ARM, D10V, SPARC, M32R, MIPS, PPC, V850, etc) 209 210`gdb-7.0/texinfo' 211 The `texinfo.tex' file, which you need in order to make a printed 212 manual using TeX. 213 214`gdb-7.0/etc' 215 Coding standards, useful files for editing GDB, and other 216 miscellanea. 217 218 Note: the following instructions are for building GDB on Unix or 219Unix-like systems. Instructions for building with DJGPP for 220MS-DOS/MS-Windows are in the file gdb/config/djgpp/README. 221 222 The simplest way to configure and build GDB is to run `configure' 223from the `gdb-VERSION-NUMBER' source directory, which in this example 224is the `gdb-7.0' directory. 225 226 First switch to the `gdb-VERSION-NUMBER' source directory if you are 227not already in it; then run `configure'. 228 229 For example: 230 231 cd gdb-7.0 232 ./configure 233 make 234 235 Running `configure' followed by `make' builds the `bfd', 236`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. 237The configured source files, and the binaries, are left in the 238corresponding source directories. 239 240 `configure' is a Bourne-shell (`/bin/sh') script; if your system 241does not recognize this automatically when you run a different shell, 242you may need to run `sh' on it explicitly: 243 244 sh configure 245 246 If you run `configure' from a directory that contains source 247directories for multiple libraries or programs, such as the `gdb-7.0' 248source directory for version 7.0, `configure' creates configuration 249files for every directory level underneath (unless you tell it not to, 250with the `--norecursion' option). 251 252 You can run the `configure' script from any of the subordinate 253directories in the GDB distribution, if you only want to configure that 254subdirectory; but be sure to specify a path to it. 255 256 For example, with version 7.0, type the following to configure only 257the `bfd' subdirectory: 258 259 cd gdb-7.0/bfd 260 ../configure 261 262 You can install `gdb' anywhere; it has no hardwired paths. However, 263you should make sure that the shell on your path (named by the `SHELL' 264environment variable) is publicly readable. Remember that GDB uses the 265shell to start your program--some systems refuse to let GDB debug child 266processes whose programs are not readable. 267 268 269Compiling GDB in another directory 270================================== 271 272 If you want to run GDB versions for several host or target machines, 273you need a different `gdb' compiled for each combination of host and 274target. `configure' is designed to make this easy by allowing you to 275generate each configuration in a separate subdirectory, rather than in 276the source directory. If your `make' program handles the `VPATH' 277feature correctly (GNU `make' and SunOS 'make' are two that should), 278running `make' in each of these directories builds the `gdb' program 279specified there. 280 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 283to specify a path to find `configure' itself from your working 284directory. If the path to `configure' would be the same as the 285argument to `--srcdir', you can leave out the `--srcdir' option; it 286will be assumed.) 287 288 For example, with version 7.0, you can build GDB in a separate 289directory for a Sun 4 like this: 290 291 cd gdb-7.0 292 mkdir ../gdb-sun4 293 cd ../gdb-sun4 294 ../gdb-7.0/configure 295 make 296 297 When `configure' builds a configuration using a remote source 298directory, 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 300the example, you'd find the Sun 4 library `libiberty.a' in the 301directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. 302 303 One popular reason to build several GDB configurations in separate 304directories is to configure GDB for cross-compiling (where GDB runs on 305one machine--the host--while debugging programs that run on another 306machine--the target). You specify a cross-debugging target by giving 307the `--target=TARGET' option to `configure'. 308 309 When you run `make' to build a program or library, you must run it 310in a configured directory--whatever directory you were in when you 311called `configure' (or one of its subdirectories). 312 313 The `Makefile' that `configure' generates in each source directory 314also runs recursively. If you type `make' in a source directory such 315as `gdb-7.0' (or in a separate configured directory configured with 316`--srcdir=PATH/gdb-7.0'), you will build all the required libraries, 317and then build GDB. 318 319 When you have multiple hosts or targets configured in separate 320directories, you can run `make' on them in parallel (for example, if 321they are NFS-mounted on each of the hosts); they will not interfere 322with each other. 323 324 325Specifying names for hosts and targets 326====================================== 327 328 The specifications used for hosts and targets in the `configure' 329script are based on a three-part naming scheme, but some short 330predefined aliases are also supported. The full naming scheme encodes 331three pieces of information in the following pattern: 332 333 ARCHITECTURE-VENDOR-OS 334 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 337`sparc-sun-sunos4'. 338 339 The `configure' script accompanying GDB does not provide any query 340facility to list all supported host and target names or aliases. 341`configure' calls the Bourne shell script `config.sub' to map 342abbreviations to full names; you can read the script, if you wish, or 343you can use it to test your guesses on abbreviations--for example: 344 345 % sh config.sub sun4 346 sparc-sun-sunos4.1.1 347 % sh config.sub sun3 348 m68k-sun-sunos4.1.1 349 % sh config.sub decstation 350 mips-dec-ultrix4.2 351 % sh config.sub hp300bsd 352 m68k-hp-bsd 353 % sh config.sub i386v 354 i386-pc-sysv 355 % sh config.sub i786v 356 Invalid configuration `i786v': machine `i786v' not recognized 357 358`config.sub' is also distributed in the GDB source directory 359(`gdb-7.0', for version 7.0). 360 361 362`configure' options 363=================== 364 365 Here is a summary of the `configure' options and arguments that are 366most often useful for building GDB. `configure' also has several other 367options not listed here. *note : (configure.info)What Configure Does, 368for a full explanation of `configure'. 369 370 configure [--help] 371 [--prefix=DIR] 372 [--srcdir=PATH] 373 [--norecursion] [--rm] 374 [--enable-build-warnings] 375 [--target=TARGET] 376 [--host=HOST] 377 [HOST] 378 379You may introduce options with a single `-' rather than `--' if you 380prefer; but you may abbreviate option names if you use `--'. 381 382`--help' 383 Display a quick summary of how to invoke `configure'. 384 385`-prefix=DIR' 386 Configure the source to install programs and files under directory 387 `DIR'. 388 389`--srcdir=PATH' 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. 400 401`--host=HOST' 402 Configure GDB to run on the specified HOST. 403 404 There is no convenient way to generate a list of all available 405 hosts. 406 407`HOST ...' 408 Same as `--host=HOST'. If you omit this, GDB will guess; it's 409 quite accurate. 410 411`--norecursion' 412 Configure only the directory level where `configure' is executed; 413 do not propagate configuration to subdirectories. 414 415`--rm' 416 Remove the configuration that the other arguments specify. 417 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 422 following flags: 423 -Wimplicit 424 -Wreturn-type 425 -Wcomment 426 -Wtrigraphs 427 -Wformat 428 -Wparentheses 429 -Wpointer-arith 430 431`--enable-werror' 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. 435 436`--target=TARGET' 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. 440 441 There is no convenient way to generate a list of all available 442 targets. 443 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'). 448 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. 457 458`--enable-64-bit-bfd' 459 Enable 64-bit support in BFD on 32-bit hosts. 460 461`--disable-gdbmi' 462 Build GDB without the GDB/MI machine interface. 463 464`--enable-tui' 465 Build GDB with the text-mode full-screen user interface (TUI). 466 Requires a curses library (ncurses and cursesX are also 467 supported). 468 469`--enable-gdbtk' 470 Build GDB with the gdbtk GUI interface. Requires TCL/Tk to be 471 installed. 472 473`--with-libunwind' 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. 477 478`--with-curses' 479 Use the curses library instead of the termcap library, for 480 text-mode terminal operations. 481 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. 487 488`--with-system-readline' 489 Use the readline library installed on the host, rather than the 490 library supplied as part of GDB tarball. 491 492`--with-expat' 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. 501 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. 512 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. 517 518`--with-sysroot=DIR' 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 525 location. 526 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. 533 534`configure' accepts other options, for compatibility with configuring 535other GNU tools recursively; but these are the only options that affect 536GDB or its supporting libraries. 537 538 539Remote debugging 540================= 541 542 The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples 543of remote stubs to be used with remote.c. They are designed to run 544standalone on an m68k, i386, or SPARC cpu and communicate properly 545with the remote.c stub over a serial line. 546 547 The directory gdb/gdbserver/ contains `gdbserver', a program that 548allows remote debugging for Unix applications. gdbserver is only 549supported for some native configurations, including Sun 3, Sun 4, and 550Linux. 551The file gdb/gdbserver/README includes further notes on gdbserver; in 552particular, it explains how to build gdbserver for cross-debugging 553(where gdbserver runs on the target machine, which is of a different 554architecture than the host machine running GDB). 555 556 There are a number of remote interfaces for talking to existing ROM 557monitors and other hardware: 558 559 remote-mips.c MIPS remote debugging protocol 560 remote-sds.c PowerPC SDS monitor 561 remote-sim.c Generalized simulator protocol 562 563 564Reporting Bugs in GDB 565===================== 566 567 There are several ways of reporting bugs in GDB. The prefered 568method is to use the World Wide Web: 569 570 http://www.gnu.org/software/gdb/bugs/ 571 572As an alternative, the bug report can be submitted, via e-mail, to the 573address "bug-gdb@gnu.org". 574 575 When submitting a bug, please include the GDB version number (e.g., 576gdb-7.0), and how you configured it (e.g., "sun4" or "mach386 host, 577i586-intel-synopsys target"). Since GDB now supports so many 578different configurations, it is important that you be precise about 579this. If at all possible, you should include the actual banner that 580GDB prints when it starts up, or failing that, the actual configure 581command that you used when configuring GDB. 582 583 For more information on how/whether to report bugs, see the 584Reporting Bugs chapter of the GDB manual (gdb/doc/gdb.texinfo). 585 586 587Graphical interface to GDB -- X Windows, MS Windows 588========================== 589 590 Several graphical interfaces to GDB are available. You should 591check: 592 593 http://www.gnu.org/software/gdb/links/ 594 595for an up-to-date list. 596 597 Emacs users will very likely enjoy the Grand Unified Debugger mode; 598try typing `M-x gdb RET'. 599 600 601Writing Code for GDB 602===================== 603 604 There is a lot of information about writing code for GDB in the 605internals manual, distributed with GDB in gdb/doc/gdbint.texinfo. You 606can read it by hand, print it by using TeX and texinfo, or process it 607into an `info' file for use with Emacs' info mode or the standalone 608`info' program. 609 610 If you are pondering writing anything but a short patch, especially 611take note of the information about copyrights in the node Submitting 612Patches. It can take quite a while to get all the paperwork done, so 613we encourage you to start that process as soon as you decide you are 614planning to work on something, or at least well ahead of when you 615think you will be ready to submit the patches. 616 617 618GDB Testsuite 619============= 620 621 Included with the GDB distribution is a DejaGNU based testsuite 622that can either be used to test your newly built GDB, or for 623regression testing a GDB with local modifications. 624 625 Running the testsuite requires the prior installation of DejaGNU, 626which is generally available via ftp. The directory 627ftp://sources.redhat.com/pub/dejagnu/ will contain a recent snapshot. 628Once DejaGNU is installed, you can run the tests in one of the 629following ways: 630 631 (1) cd gdb-7.0 632 make check-gdb 633 634or 635 636 (2) cd gdb-7.0/gdb 637 make check 638 639or 640 641 (3) cd gdb-7.0/gdb/testsuite 642 make site.exp (builds the site specific file) 643 runtest -tool gdb GDB=../gdb (or GDB=<somepath> as appropriate) 644 645When using a `make'-based method, you can use the Makefile variable 646`RUNTESTFLAGS' to pass flags to `runtest', e.g.: 647 648 make RUNTESTFLAGS=--directory=gdb.cp check 649 650If you use GNU make, you can use its `-j' option to run the testsuite 651in parallel. This can greatly reduce the amount of time it takes for 652the testsuite to run. In this case, if you set `RUNTESTFLAGS' then, 653by default, the tests will be run serially even under `-j'. You can 654override this and force a parallel run by setting the `make' variable 655`FORCE_PARALLEL' to any non-empty value. Note that the parallel `make 656check' assumes that you want to run the entire testsuite, so it is not 657compatible with some dejagnu options, like `--directory'. 658 659The last method gives you slightly more control in case of problems 660with building one or more test executables or if you are using the 661testsuite `standalone', without it being part of the GDB source tree. 662 663See the DejaGNU documentation for further details. 664 665 666(this is for editing this file with GNU emacs) 667Local Variables: 668mode: text 669End: 670