1 README for gdb-6.7.1 release 2 Updated 29, October, 2007 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-6.7.1 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-6.7.1.tar.gz file, you'll find a directory 33called `gdb-6.7.1', 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-6.7.1 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-6.7.1/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-6.7.1/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-6.7.1/configure': 72 73 /berman/migchain/source/gdb-6.7.1/configure # RIGHT 74 /berman/migchain/source/gdb-6.7.1/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-6.7.1/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-6.7.1/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-6.7.1', in the case of version 6.7.1), 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-6.7.1/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-6.7.1/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-6.7.1/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 6.7.1 distribution is in the `gdb-6.7.1' 179directory. That directory contains: 180 181`gdb-6.7.1/{COPYING,COPYING.LIB}' 182 Standard GNU license files. Please read them. 183 184`gdb-6.7.1/bfd' 185 source for the Binary File Descriptor library 186 187`gdb-6.7.1/config*' 188 script for configuring GDB, along with other support files 189 190`gdb-6.7.1/gdb' 191 the source specific to GDB itself 192 193`gdb-6.7.1/include' 194 GNU include files 195 196`gdb-6.7.1/libiberty' 197 source for the `-liberty' free software library 198 199`gdb-6.7.1/opcodes' 200 source for the library of opcode tables and disassemblers 201 202`gdb-6.7.1/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-6.7.1/sim' 208 source for some simulators (ARM, D10V, SPARC, M32R, MIPS, PPC, V850, etc) 209 210`gdb-6.7.1/texinfo' 211 The `texinfo.tex' file, which you need in order to make a printed 212 manual using TeX. 213 214`gdb-6.7.1/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-6.7.1' 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-6.7.1 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-6.7.1' 248source directory for version 6.7.1, `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 6.7.1, type the following to configure only 257the `bfd' subdirectory: 258 259 cd gdb-6.7.1/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 6.7.1, you can build GDB in a separate 289directory for a Sun 4 like this: 290 291 cd gdb-6.7.1 292 mkdir ../gdb-sun4 293 cd ../gdb-sun4 294 ../gdb-6.7.1/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-6.7.1' (or in a separate configured directory configured with 316`--srcdir=PATH/gdb-6.7.1'), 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-6.7.1', for version 6.7.1). 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`--norecursion' 402 Configure only the directory level where `configure' is executed; 403 do not propagate configuration to subdirectories. 404 405`--rm' 406 Remove the configuration that the other arguments specify. 407 408`--enable-build-warnings' 409 When building the GDB sources, ask the compiler to warn about any 410 code which looks even vaguely suspicious. You should only using 411 this feature if you're compiling with GNU CC. It passes the 412 following flags: 413 -Wimplicit 414 -Wreturn-type 415 -Wcomment 416 -Wtrigraphs 417 -Wformat 418 -Wparentheses 419 -Wpointer-arith 420 421`--target=TARGET' 422 Configure GDB for cross-debugging programs running on the specified 423 TARGET. Without this option, GDB is configured to debug programs 424 that run on the same machine (HOST) as GDB itself. 425 426 There is no convenient way to generate a list of all available 427 targets. 428 429`--host=HOST' 430 Configure GDB to run on the specified HOST. 431 432 There is no convenient way to generate a list of all available 433 hosts. 434 435`HOST ...' 436 Same as `--host=HOST'. If you omit this, GDB will guess; it's 437 quite accurate. 438 439`configure' accepts other options, for compatibility with configuring 440other GNU tools recursively; but these are the only options that affect 441GDB or its supporting libraries. 442 443 444Remote debugging 445================= 446 447 The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples 448of remote stubs to be used with remote.c. They are designed to run 449standalone on an m68k, i386, or SPARC cpu and communicate properly 450with the remote.c stub over a serial line. 451 452 The directory gdb/gdbserver/ contains `gdbserver', a program that 453allows remote debugging for Unix applications. gdbserver is only 454supported for some native configurations, including Sun 3, Sun 4, and 455Linux. 456 457 There are a number of remote interfaces for talking to existing ROM 458monitors and other hardware: 459 460 remote-mips.c MIPS remote debugging protocol 461 remote-sds.c PowerPC SDS monitor 462 remote-sim.c Generalized simulator protocol 463 464 465Reporting Bugs in GDB 466===================== 467 468 There are several ways of reporting bugs in GDB. The prefered 469method is to use the World Wide Web: 470 471 http://www.gnu.org/software/gdb/bugs/ 472 473As an alternative, the bug report can be submitted, via e-mail, to the 474address "bug-gdb@gnu.org". 475 476 When submitting a bug, please include the GDB version number (e.g., 477gdb-6.7.1), and how you configured it (e.g., "sun4" or "mach386 host, 478i586-intel-synopsys target"). Since GDB now supports so many 479different configurations, it is important that you be precise about 480this. If at all possible, you should include the actual banner that 481GDB prints when it starts up, or failing that, the actual configure 482command that you used when configuring GDB. 483 484 For more information on how/whether to report bugs, see the 485Reporting Bugs chapter of the GDB manual (gdb/doc/gdb.texinfo). 486 487 488Graphical interface to GDB -- X Windows, MS Windows 489========================== 490 491 Several graphical interfaces to GDB are available. You should 492check: 493 494 http://www.gnu.org/software/gdb/links/ 495 496for an up-to-date list. 497 498 Emacs users will very likely enjoy the Grand Unified Debugger mode; 499try typing `M-x gdb RET'. 500 501 502Writing Code for GDB 503===================== 504 505 There is a lot of information about writing code for GDB in the 506internals manual, distributed with GDB in gdb/doc/gdbint.texinfo. You 507can read it by hand, print it by using TeX and texinfo, or process it 508into an `info' file for use with Emacs' info mode or the standalone 509`info' program. 510 511 If you are pondering writing anything but a short patch, especially 512take note of the information about copyrights in the node Submitting 513Patches. It can take quite a while to get all the paperwork done, so 514we encourage you to start that process as soon as you decide you are 515planning to work on something, or at least well ahead of when you 516think you will be ready to submit the patches. 517 518 519GDB Testsuite 520============= 521 522 Included with the GDB distribution is a DejaGNU based testsuite 523that can either be used to test your newly built GDB, or for 524regression testing a GDB with local modifications. 525 526 Running the testsuite requires the prior installation of DejaGNU, 527which is generally available via ftp. The directory 528ftp://sources.redhat.com/pub/dejagnu/ will contain a recent snapshot. 529Once DejaGNU is installed, you can run the tests in one of the 530following ways: 531 532 (1) cd gdb-6.7.1 533 make check-gdb 534 535or 536 537 (2) cd gdb-6.7.1/gdb 538 make check 539 540or 541 542 (3) cd gdb-6.7.1/gdb/testsuite 543 make site.exp (builds the site specific file) 544 runtest -tool gdb GDB=../gdb (or GDB=<somepath> as appropriate) 545 546The last method gives you slightly more control in case of problems 547with building one or more test executables or if you are using the 548testsuite `standalone', without it being part of the GDB source tree. 549 550See the DejaGNU documentation for further details. 551 552 553(this is for editing this file with GNU emacs) 554Local Variables: 555mode: text 556End: 557