gdb/README

   1                       README for gdb-4.9 release
   2                     Updated 10-May-93 by Fred Fish
   3
   4 This is GDB, the GNU source-level debugger, presently running under un*x.
   5 A summary of new features is in the file `NEWS'.
   6
   7
   8 Unpacking and Installation -- quick overview
   9 ==========================
  10
  11 In this release, the GDB debugger sources, the generic GNU include
  12 files, the BFD ("binary file description") library, the readline library,
  13 and other libraries all have directories of their own underneath
  14 the gdb-4.9 directory.  The idea is that a variety of GNU tools can
  15 share a common copy of these things.  Configuration scripts and
  16 makefiles exist to cruise up and down this directory tree and
  17 automatically build all the pieces in the right order.
  18
  19 When you unpack the gdb-4.9.tar.z or gdb-4.9.tar.Z file, you'll find
  20 a directory called `gdb-4.9', which contains:
  21
  22   Makefile.in      config.sub*      glob/            opcodes/
  23   README           configure*       include/         readline/
  24   bfd/             configure.in     libiberty/       texinfo/
  25   config/          etc/             mmalloc/
  26   config.guess*    gdb/             move-if-change*
  27
  28 To build GDB, you can just do:
  29
  30         cd gdb-4.9
  31         ./configure
  32         make
  33         cp gdb/gdb /usr/local/bin/gdb   (or wherever you want)
  34
  35 This will configure and build all the libraries as well as GDB.
  36 If `configure' can't determine your system type, specify one as its
  37 argument, e.g. sun4 or decstation.
  38
  39 If you get compiler warnings during this stage, see the `Reporting Bugs'
  40 section below; there are a few known problems.
  41
  42 GDB can be used as a cross-debugger, running on a machine of one type
  43 while debugging a program running on a machine of another type.  See below.
  44
  45
  46 More Documentation
  47 ******************
  48
  49    The GDB 4 release includes an already-formatted reference card,
  50 ready for printing with PostScript or GhostScript, in the `gdb'
  51 subdirectory of the main source directory.  (In `gdb-4.9/gdb/refcard.ps'.)
  52 If you can use PostScript or GhostScript with your printer, you can
  53 print the reference card immediately with `refcard.ps'.
  54
  55    The release also includes the source for the reference card.  You
  56 can format it, using TeX, by typing:
  57
  58      make refcard.dvi
  59
  60    The GDB reference card is designed to print in landscape mode on US
  61 "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
  62 high.  You will need to specify this form of printing as an option to
  63 your DVI output program.
  64
  65    All the documentation for GDB comes as part of the machine-readable
  66 distribution.  The documentation is written in Texinfo format, which is
  67 a documentation system that uses a single source file to produce both
  68 on-line information and a printed manual.  You can use one of the Info
  69 formatting commands to create the on-line version of the documentation
  70 and TeX (or `texi2roff') to typeset the printed version.
  71
  72    GDB includes an already formatted copy of the on-line Info version of
  73 this manual in the `gdb' subdirectory.  The main Info file is
  74 `gdb-VERSION-NUMBER/gdb/gdb.info', and it refers to subordinate files
  75 matching `gdb.info*' in the same directory.  If necessary, you can
  76 print out these files, or read them with any editor; but they are
  77 easier to read using the `info' subsystem in GNU Emacs or the
  78 standalone `info' program, available as part of the GNU Texinfo
  79 distribution.
  80
  81    If you want to format these Info files yourself, you need one of the
  82 Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
  83
  84    If you have `makeinfo' installed, and are in the top level GDB
  85 source directory (`gdb-4.9', in the case of version 4.9), you can make
  86 the Info file by typing:
  87
  88      cd gdb
  89      make gdb.info
  90
  91    If you want to typeset and print copies of this manual, you need TeX,
  92 a program to print its DVI output files, and `texinfo.tex', the Texinfo
  93 definitions file.
  94
  95    TeX is a typesetting program; it does not print files directly, but
  96 produces output files called DVI files.  To print a typeset document,
  97 you need a program to print DVI files.  If your system has TeX
  98 installed, chances are it has such a program.  The precise command to
  99 use depends on your system; `lpr -d' is common; another (for PostScript
 100 devices) is `dvips'.  The DVI print command may require a file name
 101 without any extension or a `.dvi' extension.
 102
 103    TeX also requires a macro definitions file called `texinfo.tex'.
 104 This file tells TeX how to typeset a document written in Texinfo
 105 format.  On its own, TeX cannot read, much less typeset a Texinfo file.
 106  `texinfo.tex' is distributed with GDB and is located in the
 107 `gdb-VERSION-NUMBER/texinfo' directory.
 108
 109    If you have TeX and a DVI printer program installed, you can typeset
 110 and print this manual.  First switch to the the `gdb' subdirectory of
 111 the main source directory (for example, to `gdb-4.9/gdb') and then type:
 112
 113      make gdb.dvi
 114
 115
 116 Installing GDB
 117 **************
 118
 119    GDB comes with a `configure' script that automates the process of
 120 preparing GDB for installation; you can then use `make' to build the
 121 `gdb' program.
 122
 123    The GDB distribution includes all the source code you need for GDB in
 124 a single directory, whose name is usually composed by appending the
 125 version number to `gdb'.
 126
 127    For example, the GDB version 4.9 distribution is in the `gdb-4.9'
 128 directory.  That directory contains:
 129
 130 `gdb-4.9/configure (and supporting files)'
 131      script for configuring GDB and all its supporting libraries.
 132
 133 `gdb-4.9/gdb'
 134      the source specific to GDB itself
 135
 136 `gdb-4.9/bfd'
 137      source for the Binary File Descriptor library
 138
 139 `gdb-4.9/include'
 140      GNU include files
 141
 142 `gdb-4.9/libiberty'
 143      source for the `-liberty' free software library
 144
 145 `gdb-4.9/opcodes'
 146      source for the library of opcode tables and disassemblers
 147
 148 `gdb-4.9/readline'
 149      source for the GNU command-line interface
 150
 151 `gdb-4.9/glob'
 152      source for the GNU filename pattern-matching subroutine
 153
 154 `gdb-4.9/mmalloc'
 155      source for the GNU memory-mapped malloc package
 156
 157 'gdb-4.9/sim'
 158      source for some simulators (z8000, H8/300, H8/500, etc)
 159
 160    The simplest way to configure and build GDB is to run `configure'
 161 from the `gdb-VERSION-NUMBER' source directory, which in this example
 162 is the `gdb-4.9' directory.
 163
 164    First switch to the `gdb-VERSION-NUMBER' source directory if you are
 165 not already in it; then run `configure'.  Pass the identifier for the
 166 platform on which GDB will run as an argument.
 167
 168    For example:
 169
 170      cd gdb-4.9
 171      ./configure HOST
 172      make
 173
 174 where HOST is an identifier such as `sun4' or `decstation', that
 175 identifies the platform where GDB will run.
 176
 177    Running `configure HOST' followed by `make' builds the `bfd',
 178 `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
 179 The configured source files, and the binaries, are left in the
 180 corresponding source directories.
 181
 182    `configure' is a Bourne-shell (`/bin/sh') script; if your system
 183 does not recognize this automatically when you run a different shell,
 184 you may need to run `sh' on it explicitly:
 185
 186      sh configure HOST
 187
 188    If you run `configure' from a directory that contains source
 189 directories for multiple libraries or programs, such as the `gdb-4.9'
 190 source directory for version 4.9, `configure' creates configuration
 191 files for every directory level underneath (unless you tell it not to,
 192 with the `--norecursion' option).
 193
 194    You can run the `configure' script from any of the subordinate
 195 directories in the GDB distribution, if you only want to configure that
 196 subdirectory; but be sure to specify a path to it.
 197
 198    For example, with version 4.9, type the following to configure only
 199 the `bfd' subdirectory:
 200
 201      cd gdb-4.9/bfd
 202      ../configure HOST
 203
 204    You can install `gdb' anywhere; it has no hardwired paths. However,
 205 you should make sure that the shell on your path (named by the `SHELL'
 206 environment variable) is publicly readable.  Remember that GDB uses the
 207 shell to start your program--some systems refuse to let GDB debug child
 208 processes whose programs are not readable.
 209
 210
 211 Compiling GDB in another directory
 212 ==================================
 213
 214    If you want to run GDB versions for several host or target machines,
 215 you need a different `gdb' compiled for each combination of host and
 216 target.  `configure' is designed to make this easy by allowing you to
 217 generate each configuration in a separate subdirectory, rather than in
 218 the source directory.  If your `make' program handles the `VPATH'
 219 feature correctly (GNU `make' and SunOS 'make' are two that should),
 220 running `make' in each of these directories builds the `gdb' program
 221 specified there.
 222
 223    To build `gdb' in a separate directory, run `configure' with the
 224 `--srcdir' option to specify where to find the source. (You also need
 225 to specify a path to find `configure' itself from your working
 226 directory.  If the path to `configure' would be the same as the
 227 argument to `--srcdir', you can leave out the `--srcdir' option; it
 228 will be assumed.)
 229
 230    For example, with version 4.9, you can build GDB in a separate
 231 directory for a Sun 4 like this:
 232
 233      cd gdb-4.9
 234      mkdir ../gdb-sun4
 235      cd ../gdb-sun4
 236      ../gdb-4.9/configure sun4
 237      make
 238
 239    When `configure' builds a configuration using a remote source
 240 directory, it creates a tree for the binaries with the same structure
 241 (and using the same names) as the tree under the source directory.  In
 242 the example, you'd find the Sun 4 library `libiberty.a' in the
 243 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
 244
 245    One popular reason to build several GDB configurations in separate
 246 directories is to configure GDB for cross-compiling (where GDB runs on
 247 one machine--the host--while debugging programs that run on another
 248 machine--the target).  You specify a cross-debugging target by giving
 249 the `--target=TARGET' option to `configure'.
 250
 251    When you run `make' to build a program or library, you must run it
 252 in a configured directory--whatever directory you were in when you
 253 called `configure' (or one of its subdirectories).
 254
 255    The `Makefile' that `configure' generates in each source directory
 256 also runs recursively.  If you type `make' in a source directory such
 257 as `gdb-4.9' (or in a separate configured directory configured with
 258 `--srcdir=PATH/gdb-4.9'), you will build all the required libraries,
 259 and then build GDB.
 260
 261    When you have multiple hosts or targets configured in separate
 262 directories, you can run `make' on them in parallel (for example, if
 263 they are NFS-mounted on each of the hosts); they will not interfere
 264 with each other.
 265
 266
 267 Specifying names for hosts and targets
 268 ======================================
 269
 270    The specifications used for hosts and targets in the `configure'
 271 script are based on a three-part naming scheme, but some short
 272 predefined aliases are also supported.  The full naming scheme encodes
 273 three pieces of information in the following pattern:
 274
 275      ARCHITECTURE-VENDOR-OS
 276
 277    For example, you can use the alias `sun4' as a HOST argument or in a
 278 `--target=TARGET' option.  The equivalent full name is
 279 `sparc-sun-sunos4'.
 280
 281    The `configure' script accompanying GDB does not provide any query
 282 facility to list all supported host and target names or aliases.
 283 `configure' calls the Bourne shell script `config.sub' to map
 284 abbreviations to full names; you can read the script, if you wish, or
 285 you can use it to test your guesses on abbreviations--for example:
 286
 287      % sh config.sub sun4
 288      sparc-sun-sunos411
 289      % sh config.sub sun3
 290      m68k-sun-sunos411
 291      % sh config.sub decstation
 292      mips-dec-ultrix42
 293      % sh config.sub hp300bsd
 294      m68k-hp-bsd
 295      % sh config.sub i386v
 296      i386-unknown-sysv
 297      % sh config.sub i786v
 298      Invalid configuration `i786v': machine `i786v' not recognized
 299
 300 `config.sub' is also distributed in the GDB source directory
 301 (`gdb-4.9', for version 4.9).
 302
 303
 304 `configure' options
 305 ===================
 306
 307    Here is a summary of the `configure' options and arguments that are
 308 most often useful for building GDB.  `configure' also has several other
 309 options not listed here.  *note : (configure.info)What Configure Does,
 310 for a full explanation of `configure'.
 311
 312      configure [--help]
 313                [--prefix=DIR]
 314                [--srcdir=PATH]
 315                [--norecursion] [--rm]
 316                [--target=TARGET] HOST
 317
 318 You may introduce options with a single `-' rather than `--' if you
 319 prefer; but you may abbreviate option names if you use `--'.
 320
 321 `--help'
 322      Display a quick summary of how to invoke `configure'.
 323
 324 `-prefix=DIR'
 325      Configure the source to install programs and files under directory
 326      `DIR'.
 327
 328 `--srcdir=PATH'
 329      *Warning: using this option requires GNU `make', or another `make'
 330      that compatibly implements the `VPATH' feature.*
 331      Use this option to make configurations in directories separate
 332      from the GDB source directories.  Among other things, you can use
 333      this to build (or maintain) several configurations simultaneously,
 334      in separate directories.  `configure' writes configuration
 335      specific files in the current directory, but arranges for them to
 336      use the source in the directory PATH.  `configure' will create
 337      directories under the working directory in parallel to the source
 338      directories below PATH.
 339
 340 `--norecursion'
 341      Configure only the directory level where `configure' is executed;
 342      do not propagate configuration to subdirectories.
 343
 344 `--rm'
 345      Remove the configuration that the other arguments specify.
 346
 347 `--target=TARGET'
 348      Configure GDB for cross-debugging programs running on the specified
 349      TARGET.  Without this option, GDB is configured to debug programs
 350      that run on the same machine (HOST) as GDB itself.
 351
 352      There is no convenient way to generate a list of all available
 353      targets.
 354
 355 `HOST ...'
 356      Configure GDB to run on the specified HOST.
 357
 358      There is no convenient way to generate a list of all available
 359      hosts.
 360
 361 `configure' accepts other options, for compatibility with configuring
 362 other GNU tools recursively; but these are the only options that affect
 363 GDB or its supporting libraries.
 364
 365
 366 Languages other than C
 367 =======================
 368
 369 GDB provides some support for debugging C++ progams.  Partial Modula-2
 370 and Chill support is now in GDB.  GDB should work with FORTRAN programs.
 371 (If you have problems, please send a bug report; you may have to refer to
 372 some FORTRAN variables with a trailing underscore).  Pascal programs which
 373 use sets, subranges, file variables, or nested functions will not
 374 currently work.
 375
 376
 377 Kernel debugging
 378 =================
 379
 380 I have't done this myself so I can't really offer any advice.
 381 Remote debugging over serial lines works fine, but the kernel debugging
 382 code in here has not been tested in years.  Van Jacobson has
 383 better kernel debugging, but the UC lawyers won't let FSF have it.
 384
 385
 386 Remote debugging
 387 =================
 388
 389 The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples of
 390 remote stubs to be used with remote.c.  They are designed to run
 391 standalone on an m68k, i386, or SPARC cpu and communicate properly with
 392 the remote.c stub over a serial line.
 393
 394 The file rem-multi.shar contains a general stub that can probably
 395 run on various different flavors of unix to allow debugging over a
 396 serial line from one machine to another.
 397
 398 Some working remote interfaces for talking to existing ROM monitors
 399 are:
 400         remote-adapt.c   AMD 29000 "Adapt"
 401         remote-eb.c      AMD 29000 "EBMON"
 402         remote-es1800.c  Ericsson 1800 monitor
 403         remote-hms.c     Hitachi Micro Systems H8/300 monitor
 404         remote-mips.c    MIPS remote debugging protocol
 405         remote-mm.c      AMD 29000 "minimon"
 406         remote-nindy.c   Intel 960 "Nindy"
 407         remote-sim.c     Generalized simulator protocol
 408         remote-st2000.c  Tandem ST-2000 monitor
 409         remote-udi.c     AMD 29000 using the AMD "Universal Debug Interface"
 410         remote-vx.c      VxWorks realtime kernel
 411         remote-z8k.c     Zilog Z8000 simulator
 412
 413 Remote-vx.c and the vx-share subdirectory contain a remote interface for the
 414 VxWorks realtime kernel, which communicates over TCP using the Sun
 415 RPC library.  This would be a useful starting point for other remote-
 416 via-ethernet back ends.
 417
 418 Remote-udi.c and the 29k-share subdirectory contain a remote interface
 419 for AMD 29000 programs, which uses the AMD "Universal Debug Interface".
 420 This allows GDB to talk to software simulators, emulators, and/or bare
 421 hardware boards, via network or serial interfaces.  Note that GDB only
 422 provides an interface that speaks UDI, not a complete solution.  You
 423 will need something on the other end that also speaks UDI.
 424
 425
 426 Reporting Bugs
 427 ===============
 428
 429 The correct address for reporting bugs found in gdb is
 430 "bug-gdb@prep.ai.mit.edu".  Please email all bugs, and all requests for
 431 help with GDB, to that address.  Please include the GDB version number
 432 (e.g. gdb-4.9), and how you configured it (e.g. "sun4" or "mach386
 433 host, i586-intel-synopsys target").  If you include the banner that GDB
 434 prints when it starts up, that will give us enough information.
 435
 436 For more information on how/whether to report bugs, see the GDB Bugs
 437 section of the GDB manual (gdb/doc/gdb.texinfo).
 438
 439 Known bugs:
 440
 441   * Under Ultrix 4.2 (DECstation-3100), we have seen problems with backtraces
 442     after interrupting the inferior out of a read().  The problem is caused by
 443     ptrace() returning an incorrect value for register 30.  As far as we can
 444     tell, this is a kernel problem.  Any help with this would be greatly
 445     appreciated.
 446
 447   * On the SPARC GDB reports incorrect values of struct arguments to
 448     functions, for the seventh and subsequent arguments.  We have been looking
 449     at this but no fix is available yet.
 450
 451   * On DECstations there are warnings about shift counts out of range in
 452     various BFD modules.  None of them is a cause for alarm, they are actually
 453     a result of bugs in the DECstation compiler.
 454
 455   * On Solaris using the "run" command when the program is already running
 456     restarts the program, but may leave a core dump from the previous
 457     execution in the current directory.  Other SVR4 based systems don't seem
 458     to have this problem, using the same gdb source code.
 459
 460 GDB can produce warnings about symbols that it does not understand.  By
 461 default, these warnings are disabled.  You can enable them by executing
 462 `set complaint 10' (which you can put in your ~/.gdbinit if you like).
 463 I recommend doing this if you are working on a compiler, assembler,
 464 linker, or gdb, since it will point out problems that you may be able
 465 to fix.  Warnings produced during symbol reading indicate some mismatch
 466 between the object file and GDB's symbol reading code.  In many cases,
 467 it's a mismatch between the specs for the object file format, and what
 468 the compiler actually outputs or the debugger actually understands.
 469
 470
 471 X Windows versus GDB
 472 =====================
 473
 474 There is an "xxgdb", which seems to work for simple operations,
 475 which was posted to comp.sources.x.
 476
 477 For those interested in auto display of source and the availability of
 478 an editor while debugging I suggest trying gdb-mode in gnu-emacs
 479 (Try typing M-x gdb RETURN).  Comments on this mode are welcome.
 480
 481
 482 Writing Code for GDB
 483 =====================
 484
 485 There is a lot of information about writing code for GDB in the
 486 internals manual, distributed with GDB in gdb/doc/gdbint.texinfo.  You
 487 can read it by hand, print it by using TeX and texinfo, or process it
 488 into an `info' file for use with Emacs' info mode or the standalone
 489 `info' program.  In particular, see the nodes Getting Started,
 490 Debugging GDB, New Architectures, Coding Style, Clean Design, and
 491 Submitting Patches.
 492
 493 If you are pondering writing anything but a short patch, especially
 494 take note of the information about copyrights in the node Submitting
 495 Patches.  It can take quite a while to get all the paperwork done, so
 496 we encourage you to start that process as soon as you decide you are
 497 planning to work on something, or at least well ahead of when you
 498 think you will be ready to submit the patches.
 499
 500
 501 GDB Testsuite
 502 =============
 503
 504 There is a dejagnu based testsuite available for testing your newly
 505 built gdb, or for regression testing gdb's with local modifications.
 506 The testsuite is distributed separately from the base gdb distribution
 507 for the convenience of people that wish to get either gdb or the testsuite
 508 separately.
 509
 510 The name of the testsuite is gdb-4.9-testsuite.tar.z.  You unpack it in the
 511 same directory in which you unpacked the base gdb distribution, and it
 512 will create and populate the directory gdb-4.9/gdb/testsuite.
 513
 514 Running the testsuite requires the prior installation of dejagnu, which
 515 should be available via ftp.  Once dejagnu is installed, you can run
 516 the tests in one of two ways:
 517
 518   (1)   cd gdb-4.9/gdb          (assuming you also unpacked gdb)
 519         make check
 520
 521 or
 522
 523   (2)   cd gdb-4.9/gdb/testsuite
 524         make            (builds the test executables)
 525         make site.exp   (builds the site specific file)
 526         runtest -tool gdb GDB=../gdb    (or GDB=<somepath> as appropriate)
 527
 528 The second method gives you slightly more control in case of problems with
 529 building one or more test executables, in case you wish to remove some
 530 test executables before running the tests, or if you are using the testsuite
 531 'standalone', without it being part of the gdb source tree.
 532
 533 See the dejagnu documentation for further details.
 534
 535 \f
 536 (this is for editing this file with GNU emacs)
 537 Local Variables:
 538 mode: text
 539 End: