1 README for gdb-6.3 release 2 Updated 8, November, 2004 by Andrew Cagney 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.3 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.3.tar.gz file, you'll find a directory 33called `gdb-6.3', which contains: 34 35 COPYING config-ml.in gdb ltcf-gcj.sh readline 36 COPYING.LIB config.guess gettext.m4 ltconfig sim 37 Makefile.def config.if include ltmain.sh src-release 38 Makefile.in config.sub install-sh md5.sum symlink-tree 39 Makefile.tpl configure libiberty missing texinfo 40 README configure.in libtool.m4 mkinstalldirs ylwrap 41 bfd djunpack.bat ltcf-c.sh move-if-change 42 config etc ltcf-cxx.sh opcodes 43 44You can build GDB right in the source directory: 45 46 cd gdb-6.3 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.3/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.3/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.3/configure': 72 73 /berman/migchain/source/gdb-6.3/configure # RIGHT 74 /berman/migchain/source/gdb-6.3/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.3/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'. 91 92 GDB can be used as a cross-debugger, running on a machine of one 93type while debugging a program running on a machine of another type. 94See below. 95 96 97More Documentation 98****************** 99 100 All the documentation for GDB comes as part of the machine-readable 101distribution. The documentation is written in Texinfo format, which 102is a documentation system that uses a single source file to produce 103both on-line information and a printed manual. You can use one of the 104Info formatting commands to create the on-line version of the 105documentation and TeX (or `texi2roff') to typeset the printed version. 106 107 GDB includes an already formatted copy of the on-line Info version 108of this manual in the `gdb/doc' subdirectory. The main Info file is 109`gdb-6.3/gdb/doc/gdb.info', and it refers to subordinate files 110matching `gdb.info*' in the same directory. If necessary, you can 111print out these files, or read them with any editor; but they are 112easier to read using the `info' subsystem in GNU Emacs or the 113standalone `info' program, available as part of the GNU Texinfo 114distribution. 115 116 If you want to format these Info files yourself, you need one of the 117Info formatting programs, such as `texinfo-format-buffer' or 118`makeinfo'. 119 120 If you have `makeinfo' installed, and are in the top level GDB 121source directory (`gdb-6.3', in the case of version 6.3), you can make 122the Info file by typing: 123 124 cd gdb/doc 125 make info 126 127 If you want to typeset and print copies of this manual, you need 128TeX, a program to print its DVI output files, and `texinfo.tex', the 129Texinfo definitions file. This file is included in the GDB 130distribution, in the directory `gdb-6.3/texinfo'. 131 132 TeX is a typesetting program; it does not print files directly, but 133produces output files called DVI files. To print a typeset document, 134you need a program to print DVI files. If your system has TeX 135installed, chances are it has such a program. The precise command to 136use depends on your system; `lpr -d' is common; another (for PostScript 137devices) is `dvips'. The DVI print command may require a file name 138without any extension or a `.dvi' extension. 139 140 TeX also requires a macro definitions file called `texinfo.tex'. 141This file tells TeX how to typeset a document written in Texinfo 142format. On its own, TeX cannot read, much less typeset a Texinfo file. 143 `texinfo.tex' is distributed with GDB and is located in the 144`gdb-6.3/texinfo' directory. 145 146 If you have TeX and a DVI printer program installed, you can typeset 147and print this manual. First switch to the the `gdb' subdirectory of 148the main source directory (for example, to `gdb-6.3/gdb') and then type: 149 150 make doc/gdb.dvi 151 152 If you prefer to have the manual in PDF format, type this from the 153`gdb/doc' subdirectory of the main source directory: 154 155 make gdb.pdf 156 157For this to work, you will need the PDFTeX package to be installed. 158 159 160Installing GDB 161************** 162 163 GDB comes with a `configure' script that automates the process of 164preparing GDB for installation; you can then use `make' to build the 165`gdb' program. 166 167 The GDB distribution includes all the source code you need for GDB in 168a single directory, whose name is usually composed by appending the 169version number to `gdb'. 170 171 For example, the GDB version 6.3 distribution is in the `gdb-6.3' 172directory. That directory contains: 173 174`gdb-6.3/{COPYING,COPYING.LIB}' 175 Standard GNU license files. Please read them. 176 177`gdb-6.3/bfd' 178 source for the Binary File Descriptor library 179 180`gdb-6.3/config*' 181 script for configuring GDB, along with other support files 182 183`gdb-6.3/gdb' 184 the source specific to GDB itself 185 186`gdb-6.3/include' 187 GNU include files 188 189`gdb-6.3/libiberty' 190 source for the `-liberty' free software library 191 192`gdb-6.3/opcodes' 193 source for the library of opcode tables and disassemblers 194 195`gdb-6.3/readline' 196 source for the GNU command-line interface 197 NOTE: The readline library is compiled for use by GDB, but will 198 not be installed on your system when "make install" is issued. 199 200`gdb-6.3/sim' 201 source for some simulators (ARM, D10V, SPARC, M32R, MIPS, PPC, V850, etc) 202 203`gdb-6.3/texinfo' 204 The `texinfo.tex' file, which you need in order to make a printed 205 manual using TeX. 206 207`gdb-6.3/etc' 208 Coding standards, useful files for editing GDB, and other 209 miscellanea. 210 211 Note: the following instructions are for building GDB on Unix or 212Unix-like systems. Instructions for building with DJGPP for 213MS-DOS/MS-Windows are in the file gdb/config/djgpp/README. 214 215 The simplest way to configure and build GDB is to run `configure' 216from the `gdb-VERSION-NUMBER' source directory, which in this example 217is the `gdb-6.3' directory. 218 219 First switch to the `gdb-VERSION-NUMBER' source directory if you are 220not already in it; then run `configure'. 221 222 For example: 223 224 cd gdb-6.3 225 ./configure 226 make 227 228 Running `configure' followed by `make' builds the `bfd', 229`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. 230The configured source files, and the binaries, are left in the 231corresponding source directories. 232 233 `configure' is a Bourne-shell (`/bin/sh') script; if your system 234does not recognize this automatically when you run a different shell, 235you may need to run `sh' on it explicitly: 236 237 sh configure 238 239 If you run `configure' from a directory that contains source 240directories for multiple libraries or programs, such as the `gdb-6.3' 241source directory for version 6.3, `configure' creates configuration 242files for every directory level underneath (unless you tell it not to, 243with the `--norecursion' option). 244 245 You can run the `configure' script from any of the subordinate 246directories in the GDB distribution, if you only want to configure that 247subdirectory; but be sure to specify a path to it. 248 249 For example, with version 6.3, type the following to configure only 250the `bfd' subdirectory: 251 252 cd gdb-6.3/bfd 253 ../configure 254 255 You can install `gdb' anywhere; it has no hardwired paths. However, 256you should make sure that the shell on your path (named by the `SHELL' 257environment variable) is publicly readable. Remember that GDB uses the 258shell to start your program--some systems refuse to let GDB debug child 259processes whose programs are not readable. 260 261 262Compiling GDB in another directory 263================================== 264 265 If you want to run GDB versions for several host or target machines, 266you need a different `gdb' compiled for each combination of host and 267target. `configure' is designed to make this easy by allowing you to 268generate each configuration in a separate subdirectory, rather than in 269the source directory. If your `make' program handles the `VPATH' 270feature correctly (GNU `make' and SunOS 'make' are two that should), 271running `make' in each of these directories builds the `gdb' program 272specified there. 273 274 To build `gdb' in a separate directory, run `configure' with the 275`--srcdir' option to specify where to find the source. (You also need 276to specify a path to find `configure' itself from your working 277directory. If the path to `configure' would be the same as the 278argument to `--srcdir', you can leave out the `--srcdir' option; it 279will be assumed.) 280 281 For example, with version 6.3, you can build GDB in a separate 282directory for a Sun 4 like this: 283 284 cd gdb-6.3 285 mkdir ../gdb-sun4 286 cd ../gdb-sun4 287 ../gdb-6.3/configure 288 make 289 290 When `configure' builds a configuration using a remote source 291directory, it creates a tree for the binaries with the same structure 292(and using the same names) as the tree under the source directory. In 293the example, you'd find the Sun 4 library `libiberty.a' in the 294directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. 295 296 One popular reason to build several GDB configurations in separate 297directories is to configure GDB for cross-compiling (where GDB runs on 298one machine--the host--while debugging programs that run on another 299machine--the target). You specify a cross-debugging target by giving 300the `--target=TARGET' option to `configure'. 301 302 When you run `make' to build a program or library, you must run it 303in a configured directory--whatever directory you were in when you 304called `configure' (or one of its subdirectories). 305 306 The `Makefile' that `configure' generates in each source directory 307also runs recursively. If you type `make' in a source directory such 308as `gdb-6.3' (or in a separate configured directory configured with 309`--srcdir=PATH/gdb-6.3'), you will build all the required libraries, 310and then build GDB. 311 312 When you have multiple hosts or targets configured in separate 313directories, you can run `make' on them in parallel (for example, if 314they are NFS-mounted on each of the hosts); they will not interfere 315with each other. 316 317 318Specifying names for hosts and targets 319====================================== 320 321 The specifications used for hosts and targets in the `configure' 322script are based on a three-part naming scheme, but some short 323predefined aliases are also supported. The full naming scheme encodes 324three pieces of information in the following pattern: 325 326 ARCHITECTURE-VENDOR-OS 327 328 For example, you can use the alias `sun4' as a HOST argument or in a 329`--target=TARGET' option. The equivalent full name is 330`sparc-sun-sunos4'. 331 332 The `configure' script accompanying GDB does not provide any query 333facility to list all supported host and target names or aliases. 334`configure' calls the Bourne shell script `config.sub' to map 335abbreviations to full names; you can read the script, if you wish, or 336you can use it to test your guesses on abbreviations--for example: 337 338 % sh config.sub sun4 339 sparc-sun-sunos4.1.1 340 % sh config.sub sun3 341 m68k-sun-sunos4.1.1 342 % sh config.sub decstation 343 mips-dec-ultrix4.2 344 % sh config.sub hp300bsd 345 m68k-hp-bsd 346 % sh config.sub i386v 347 i386-pc-sysv 348 % sh config.sub i786v 349 Invalid configuration `i786v': machine `i786v' not recognized 350 351`config.sub' is also distributed in the GDB source directory 352(`gdb-6.3', for version 6.3). 353 354 355`configure' options 356=================== 357 358 Here is a summary of the `configure' options and arguments that are 359most often useful for building GDB. `configure' also has several other 360options not listed here. *note : (configure.info)What Configure Does, 361for a full explanation of `configure'. 362 363 configure [--help] 364 [--prefix=DIR] 365 [--srcdir=PATH] 366 [--norecursion] [--rm] 367 [--enable-build-warnings] 368 [--target=TARGET] 369 [--host=HOST] 370 [HOST] 371 372You may introduce options with a single `-' rather than `--' if you 373prefer; but you may abbreviate option names if you use `--'. 374 375`--help' 376 Display a quick summary of how to invoke `configure'. 377 378`-prefix=DIR' 379 Configure the source to install programs and files under directory 380 `DIR'. 381 382`--srcdir=PATH' 383 *Warning: using this option requires GNU `make', or another `make' 384 that compatibly implements the `VPATH' feature.* 385 Use this option to make configurations in directories separate 386 from the GDB source directories. Among other things, you can use 387 this to build (or maintain) several configurations simultaneously, 388 in separate directories. `configure' writes configuration 389 specific files in the current directory, but arranges for them to 390 use the source in the directory PATH. `configure' will create 391 directories under the working directory in parallel to the source 392 directories below PATH. 393 394`--norecursion' 395 Configure only the directory level where `configure' is executed; 396 do not propagate configuration to subdirectories. 397 398`--rm' 399 Remove the configuration that the other arguments specify. 400 401`--enable-build-warnings' 402 When building the GDB sources, ask the compiler to warn about any 403 code which looks even vaguely suspicious. You should only using 404 this feature if you're compiling with GNU CC. It passes the 405 following flags: 406 -Wimplicit 407 -Wreturn-type 408 -Wcomment 409 -Wtrigraphs 410 -Wformat 411 -Wparentheses 412 -Wpointer-arith 413 414`--target=TARGET' 415 Configure GDB for cross-debugging programs running on the specified 416 TARGET. Without this option, GDB is configured to debug programs 417 that run on the same machine (HOST) as GDB itself. 418 419 There is no convenient way to generate a list of all available 420 targets. 421 422`--host=HOST' 423 Configure GDB to run on the specified HOST. 424 425 There is no convenient way to generate a list of all available 426 hosts. 427 428`HOST ...' 429 Same as `--host=HOST'. If you omit this, GDB will guess; it's 430 quite accurate. 431 432`configure' accepts other options, for compatibility with configuring 433other GNU tools recursively; but these are the only options that affect 434GDB or its supporting libraries. 435 436 437Remote debugging 438================= 439 440 The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples 441of remote stubs to be used with remote.c. They are designed to run 442standalone on an m68k, i386, or SPARC cpu and communicate properly 443with the remote.c stub over a serial line. 444 445 The directory gdb/gdbserver/ contains `gdbserver', a program that 446allows remote debugging for Unix applications. gdbserver is only 447supported for some native configurations, including Sun 3, Sun 4, and 448Linux. 449 450 There are a number of remote interfaces for talking to existing ROM 451monitors and other hardware: 452 453 remote-e7000.c Renesas E7000 ICE 454 remote-est.c EST emulator 455 remote-hms.c Renesas Micro Systems H8/300 monitor 456 remote-mips.c MIPS remote debugging protocol 457 remote-rdi.c ARM with Angel monitor 458 remote-rdp.c ARM with Demon monitor 459 remote-sds.c PowerPC SDS monitor 460 remote-sim.c Generalized simulator protocol 461 remote-st.c Tandem ST-2000 monitor 462 remote-vx.c VxWorks realtime kernel 463 464 Remote-vx.c and the vx-share subdirectory contain a remote 465interface for the VxWorks realtime kernel, which communicates over TCP 466using the Sun RPC library. This would be a useful starting point for 467other remote- via-ethernet back ends. 468 469 470Reporting Bugs in GDB 471===================== 472 473 There are several ways of reporting bugs in GDB. The prefered 474method is to use the World Wide Web: 475 476 http://www.gnu.org/software/gdb/bugs/ 477 478As an alternative, the bug report can be submitted, via e-mail, to the 479address "bug-gdb@gnu.org". 480 481 When submitting a bug, please include the GDB version number (e.g., 482gdb-6.3), and how you configured it (e.g., "sun4" or "mach386 host, 483i586-intel-synopsys target"). Since GDB now supports so many 484different configurations, it is important that you be precise about 485this. If at all possible, you should include the actual banner that 486GDB prints when it starts up, or failing that, the actual configure 487command that you used when configuring GDB. 488 489 For more information on how/whether to report bugs, see the 490Reporting Bugs chapter of the GDB manual (gdb/doc/gdb.texinfo). 491 492 493Graphical interface to GDB -- X Windows, MS Windows 494========================== 495 496 Several graphical interfaces to GDB are available. You should 497check: 498 499 http://www.gnu.org/software/gdb/links/ 500 501for an up-to-date list. 502 503 Emacs users will very likely enjoy the Grand Unified Debugger mode; 504try typing `M-x gdb RET'. 505 506 507Writing Code for GDB 508===================== 509 510 There is a lot of information about writing code for GDB in the 511internals manual, distributed with GDB in gdb/doc/gdbint.texinfo. You 512can read it by hand, print it by using TeX and texinfo, or process it 513into an `info' file for use with Emacs' info mode or the standalone 514`info' program. 515 516 If you are pondering writing anything but a short patch, especially 517take note of the information about copyrights in the node Submitting 518Patches. It can take quite a while to get all the paperwork done, so 519we encourage you to start that process as soon as you decide you are 520planning to work on something, or at least well ahead of when you 521think you will be ready to submit the patches. 522 523 524GDB Testsuite 525============= 526 527 Included with the GDB distribution is a DejaGNU based testsuite 528that can either be used to test your newly built GDB, or for 529regression testing a GDB with local modifications. 530 531 Running the testsuite requires the prior installation of DejaGNU, 532which is generally available via ftp. The directory 533ftp://sources.redhat.com/pub/dejagnu/ will contain a recent snapshot. 534Once DejaGNU is installed, you can run the tests in one of the 535following ways: 536 537 (1) cd gdb-6.3 538 make check-gdb 539 540or 541 542 (2) cd gdb-6.3/gdb 543 make check 544 545or 546 547 (3) cd gdb-6.3/gdb/testsuite 548 make site.exp (builds the site specific file) 549 runtest -tool gdb GDB=../gdb (or GDB=<somepath> as appropriate) 550 551The last method gives you slightly more control in case of problems 552with building one or more test executables or if you are using the 553testsuite `standalone', without it being part of the GDB source tree. 554 555See the DejaGNU documentation for further details. 556 557 558(this is for editing this file with GNU emacs) 559Local Variables: 560mode: text 561End: 562