gdb/README

   1                 README for gdb-4.4 release
   2     John Gilmore & Stu Grossman         31 Jan 1992
   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 `WHATS.NEW'.
   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 a miscellaneous library all have directories of their own underneath
  14 the gdb-4.4 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.4.tar.Z file, you'll get a directory called
  20 `gdb-4.4', which contains:
  21
  22   DOC.configure  bfd/           configure*     glob/          readline/
  23   Makefile.in    config/        configure.in   include/       texinfo/
  24   README         config.sub*    gdb/           libiberty/
  25
  26 To build GDB, you can just do:
  27
  28         cd gdb-4.4
  29         ./configure HOSTTYPE            (e.g. sun4, decstation)
  30         make
  31         cp gdb/gdb /usr/local/bin/gdb   (or wherever you want)
  32
  33 This will configure and build all the libraries as well as GDB.
  34 If you get compiler warnings during this stage, see the `Reporting Bugs'
  35 section below; there are a few known problems.
  36
  37 GDB can be used as a cross-debugger, running on a machine of one type
  38 while debugging a program running on a machine of another type.  See below.
  39
  40
  41 More Documentation
  42 ==================
  43
  44    The GDB 4 release includes an already-formatted reference card,
  45 ready for printing on a PostScript or GhostScript printer, in the `gdb'
  46 subdirectory of the main source directory--in `gdb-4.4/gdb/refcard.ps'
  47 of the version 4.4 release.  If you have a PostScript or GhostScript
  48 printer, you can print the reference card by just sending `refcard.ps'
  49 to the printer.
  50
  51    If all you have is TeX, format the GDB reference card by typing:
  52
  53      make refcard.dvi
  54
  55    The GDB reference card is designed to print in landscape mode on US
  56 "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
  57 high.  You will need to specify this form of printing as an option to
  58 your DVI output program.
  59
  60    All the documentation for GDB comes as part of the online
  61 distribution.  The documentation is written in Texinfo format,
  62 which is a documentation system that uses a single source file to
  63 produce both on-line information and a printed manual.  You can use
  64 one of the Info formatting commands to create the on-line version of
  65 the documentation and TeX (or `texi2roff') to typeset the printed
  66 version.
  67
  68    GDB includes an already formatted copy of the on-line Info version
  69 of this manual in the `gdb' subdirectory.  The main Info file is
  70 `gdb-VERSION-NUMBER/gdb/gdb.info', and it refers to subordinate files
  71 matching `gdb.info*' in the same directory.
  72
  73    If you want to format these Info files yourself, you need one of the
  74 Info formatting programs, such as `texinfo-format-buffer' or
  75 `makeinfo'.
  76
  77    If you have `makeinfo' installed, and are in the top level GDB
  78 source directory (`gdb-4.4', in the case of version 4.4), you can make
  79 the Info file by typing:
  80
  81      cd gdb
  82      make gdb.info
  83
  84    If you want to typeset and print copies of this manual, you need
  85 TeX, a printing program such as `lpr', and `texinfo.tex', the Texinfo
  86 definitions file.
  87
  88    TeX is typesetting program; it does not print files directly, but
  89 produces output files called DVI files.  To print a typeset document,
  90 you need a program to print DVI files.  If your system has TeX
  91 installed, chances are it has such a program.  The precise command to
  92 use depends on your system; `lpr -d' is common; another is `dvips'.
  93 The DVI print command may require a file name without any extension or
  94 a `.dvi' extension.
  95
  96    TeX also requires a macro definitions file called `texinfo.tex'.
  97 This file tells TeX how to typeset a document written in Texinfo
  98 format.  On its own, TeX cannot read, much less typeset a Texinfo
  99 file.  `texinfo.tex' is distributed with GDB and is located in the
 100 `gdb-VERSION-NUMBER/texinfo' directory.
 101
 102    If you have TeX and a DVI printer program installed, you can
 103 typeset and print this manual.  First switch to the the `gdb'
 104 subdirectory of the main source directory (for example, to
 105 `gdb-4.4/gdb') and then type:
 106
 107      make gdb.dvi
 108
 109 Installing GDB
 110 ==============
 111
 112    GDB comes with a `configure' script that automates the process of
 113 preparing GDB for installation; you can then use `make' to build the
 114 `gdb' program.
 115
 116    The GDB distribution includes all the source code you need for GDB
 117 in a single directory, whose name is usually composed by appending the
 118 version number to `gdb'.
 119
 120    For example, the GDB version 4.4 distribution is in the `gdb-4.4'
 121 directory.  That directory contains:
 122
 123 `gdb-4.4/configure (and supporting files)'
 124      script for configuring GDB and all its supporting libraries.
 125
 126 `gdb-4.4/gdb'
 127      the source specific to GDB itself
 128
 129 `gdb-4.4/bfd'
 130      source for the Binary File Descriptor Library
 131
 132 `gdb-4.4/include'
 133      GNU include files
 134
 135 `gdb-4.4/libiberty'
 136      source for the `-liberty' free software library
 137
 138 `gdb-4.4/readline'
 139      source for the GNU command-line interface
 140
 141    The simplest way to configure and build GDB is to run `configure'
 142 from the `gdb-VERSION-NUMBER' source directory, which in this example
 143 is the `gdb-4.4' directory.
 144
 145    First switch to the `gdb-VERSION-NUMBER' source directory if you
 146 are not already in it; then run `configure'.  Pass the identifier for
 147 the platform on which GDB will run as an argument.
 148
 149    For example:
 150
 151      cd gdb-4.4
 152      ./configure HOST
 153      make
 154
 155 where HOST is an identifier such as `sun4' or `decstation', that
 156 identifies the platform where GDB will run.
 157
 158    These `configure' and `make' commands build the three libraries `bfd',
 159 `readline', and `libiberty', then `gdb' itself.  The configured source
 160 files, and the binaries, are left in the corresponding source
 161 directories.
 162
 163    `configure' is a Bourne-shell (`/bin/sh') script; if your system
 164 does not recognize this automatically when you run a different shell,
 165 you may need to run `sh' on it explicitly:
 166
 167      sh configure HOST
 168
 169    If you run `configure' from a directory that contains source
 170 directories for multiple libraries or programs, such as the `gdb-4.4'
 171 source directory for version 4.4, `configure' creates configuration
 172 files for every directory level underneath (unless you tell it not to,
 173 with the `--norecursion' option).
 174
 175    You can run the `configure' script from any of the subordinate
 176 directories in the GDB distribution, if you only want to configure
 177 that subdirectory; but be sure to specify a path to it.
 178
 179    For example, with version 4.4, type the following to configure only
 180 the `bfd' subdirectory:
 181
 182      cd gdb-4.4/bfd
 183      ../configure HOST
 184
 185    You can install `gdb' anywhere; it has no hardwired paths.
 186 However, you should make sure that the shell on your path (named by
 187 the `SHELL' environment variable) is publicly readable.  Remember that
 188 GDB uses the shell to start your program--some systems refuse to let
 189 GDB debug child processes whose programs are not readable.
 190
 191
 192 Compiling GDB in Another Directory
 193 ==================================
 194
 195    If you want to run GDB versions for several host or target machines,
 196 you'll need a different `gdb' compiled for each combination of host
 197 and target.  `configure' is designed to make this easy by allowing you
 198 to generate each configuration in a separate subdirectory, rather than
 199 in the source directory.  If your `make' program handles the `VPATH'
 200 feature (GNU `make' does), running `make' in each of these directories
 201 then builds the `gdb' program specified there.
 202
 203    To build `gdb' in a separate directory, run `configure' with the
 204 `--srcdir' option to specify where to find the source.  (Remember,
 205 you'll also need to specify a path to find `configure' itself from
 206 your working directory.)
 207
 208    For example, with version 4.4, you can build GDB in a separate
 209 directory for a Sun 4 like this:
 210
 211      cd gdb-4.4
 212      mkdir ../gdb-sun4
 213      cd ../gdb-sun4
 214      ../gdb-4.4/configure --srcdir=../gdb-4.4 sun4
 215      make
 216
 217    When `configure' builds a configuration using a remote source
 218 directory, it creates a tree for the binaries with the same structure
 219 (and using the same names) as the tree under the source directory.  In
 220 the example, you'd find the Sun 4 library `libiberty.a' in the
 221 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
 222
 223    One popular use for building several GDB configurations in separate
 224 directories is to configure GDB for cross-compiling (where GDB runs on
 225 one machine--the host--while debugging programs that run on another
 226 machine--the target).  You specify a cross-debugging target by giving
 227 the `--target=TARGET' option to `configure'.
 228
 229    When you run `make' to build a program or library, you must run it
 230 in a configured directory--whatever directory you were in when you
 231 called `configure' (or one of its subdirectories).
 232
 233    The `Makefile' generated by `configure' for each source directory
 234 also runs recursively.  If you type `make' in a source directory such
 235 as `gdb-4.4' (or in a separate configured directory configured with
 236 `--srcdir=PATH/gdb-4.4'), you will build all the required libraries,
 237 then build GDB.
 238
 239    When you have multiple hosts or targets configured in separate
 240 directories, you can run `make' on them in parallel (for example, if
 241 they are NFS-mounted on each of the hosts); they will not interfere
 242 with each other.
 243
 244
 245 Specifying Names for Hosts and Targets
 246 ======================================
 247
 248    The specifications used for hosts and targets in the `configure'
 249 script are based on a three-part naming scheme, but some short
 250 predefined aliases are also supported.  The full naming scheme encodes
 251 three pieces of information in the following pattern:
 252
 253      ARCHITECTURE-VENDOR-OS
 254
 255    For example, you can use the alias `sun4' as a HOST argument or in
 256 a `+target=TARGET' option, but the equivalent full name is
 257 `sparc-sun-sunos4'.
 258
 259    The following table shows all the architectures, hosts, and OS
 260 prefixes that `configure' recognizes in GDB version 4.4.  Entries in
 261 the "OS prefix" column ending in a `*' may be followed by a release
 262 number.
 263
 264
 265      ARCHITECTURE  VENDOR                     OS prefix
 266      ------------+--------------------------+---------------------------
 267                  |                          |
 268       580        | altos        hp          | aix*          msdos*
 269       a29k       | amd          ibm         | amigados      newsos*
 270       alliant    | amdahl       intel       | aout          nindy*
 271       arm        | aout         isi         | bout          osf*
 272       c1         | apollo       little      | bsd*          sco*
 273       c2         | att          mips        | coff          sunos*
 274       cray2      | bcs          motorola    | ctix*         svr4
 275       h8300      | bout         ncr         | dgux*         sym*
 276       i386       | bull         next        | dynix*        sysv*
 277       i860       | cbm          nyu         | ebmon         ultrix*
 278       i960       | coff         sco         | esix*         unicos*
 279       m68000     | convergent   sequent     | hds           unos*
 280       m68k       | convex       sgi         | hpux*         uts
 281       m88k       | cray         sony        | irix*         v88r*
 282       mips       | dec          sun         | isc*          vms*
 283       ns32k      | encore       unicom      | kern          vxworks*
 284       pyramid    | gould        utek        | mach*
 285       romp       | hitachi      wrs         |
 286       rs6000     |                          |
 287       sparc      |                          |
 288       tahoe      |                          |
 289       tron       |                          |
 290       vax        |                          |
 291       xmp        |                          |
 292       ymp        |                          |
 293
 294      *Warning:* `configure' can represent a very large number of
 295      combinations of architecture, vendor, and OS.  There is by no
 296      means support available for all possible combinations!
 297
 298    The `configure' script accompanying GDB does not provide any query
 299 facility to list all supported host and target names or aliases.
 300 `configure' calls the Bourne shell script `config.sub' to map
 301 abbreviations to full names; you can read the script, if you wish, or
 302 you can use it to test your guesses on abbreviations--for example:
 303
 304      % sh config.sub sun4
 305      sparc-sun-sunos4
 306      % sh config.sub sun3
 307      m68k-sun-sunos4
 308      % sh config.sub decstation
 309      mips-dec-ultrix
 310      % sh config.sub hp300bsd
 311      m68k-hp-bsd
 312      % sh config.sub i386v
 313      i386-none-sysv
 314      % sh config.sub i486v
 315      *** Configuration "i486v" not recognized
 316
 317 `config.sub' is also distributed in the GDB source directory
 318 (`gdb-4.4', for version 4.4).
 319
 320
 321 `configure' Options
 322 ===================
 323
 324    Here is a summary of all the `configure' options and arguments that
 325 you might use for building GDB:
 326
 327      configure [--destdir=DIR] [--srcdir=PATH]
 328                [--norecursion] [--rm]
 329                [--target=TARGET] HOST
 330
 331 You may introduce options with a single `-' rather than `--' if you
 332 prefer; but you may abbreviate option names if you use `--'.
 333
 334 `--destdir=DIR'
 335      DIR is an installation directory *path prefix*.  After you
 336      configure with this option, `make install' will install GDB as
 337      `DIR/bin/gdb', and the libraries in `DIR/lib'.  If you specify
 338      `--destdir=/usr/local', for example, `make install' creates
 339      `/usr/local/bin/gdb'.
 340
 341 `--srcdir=PATH'
 342      Use this option to make configurations in directories separate
 343      from the GDB source directories.  Among other things, you can use
 344      this to build (or maintain) several configurations
 345      simultaneously, in separate directories.  `configure' writes
 346      configuration specific files in the current directory, but
 347      arranges for them to use the source in the directory PATH.
 348      `configure' will create directories under the working directory
 349      in parallel to the source directories below PATH.
 350
 351 `--norecursion'
 352      Configure only the directory level where `configure' is executed;
 353      do not propagate configuration to subdirectories.
 354
 355 `--rm'
 356      Remove the configuration that the other arguments specify.
 357
 358 `--target=TARGET'
 359      Configure GDB for cross-debugging programs running on the
 360      specified TARGET.  Without this option, GDB is configured to debug
 361      programs that run on the same machine (HOST) as GDB itself.
 362
 363      There is no convenient way to generate a list of all available
 364      targets.
 365
 366 `HOST ...'
 367      Configure GDB to run on the specified HOST.
 368
 369      There is no convenient way to generate a list of all available
 370      hosts.
 371
 372 `configure' accepts other options, for compatibility with configuring
 373 other GNU tools recursively; but these are the only options that
 374 affect GDB or its supporting libraries.
 375
 376
 377                 Languages other than C
 378
 379 GDB provides some support for debugging C++ progams.  Partial Modula-2
 380 support is now in GDB.  GDB should work with FORTRAN programs.  (If you
 381 have problems, please send a bug report; you may have to refer to some
 382 FORTRAN variables with a trailing underscore).  I am not aware of
 383 anyone who is working on getting gdb to use the syntax of any other
 384 language.  Pascal programs which use sets, subranges, file variables,
 385 or nested functions will not currently work.
 386
 387
 388                 Kernel debugging
 389
 390 I have't done this myself so I can't really offer any advice.
 391 Remote debugging over serial lines works fine, but the kernel debugging
 392 code in here has not been tested in years.  Van Jacobson claims to have
 393 better kernel debugging.
 394
 395
 396                 Remote debugging
 397
 398 The files m68k-stub.c and i386-stub.c contain two examples of remote
 399 stubs to be used with remote.c.  They are designeded to run standalone
 400 on a 68k or 386 cpu and communicate properly with the remote.c stub
 401 over a serial line.
 402
 403 The file rem-multi.shar contains a general stub that can probably
 404 run on various different flavors of unix to allow debugging over a
 405 serial line from one machine to another.
 406
 407 Some working remote interfaces for talking to existing ROM monitors
 408 are:
 409         remote-eb.c      AMD 29000 "EBMON"
 410         remote-nindy.c   Intel 960 "Nindy"
 411         remote-adapt.c   AMD 29000 "Adapt"
 412         remote-mm.c      AMD 29000 "minimon"
 413
 414 Remote-vx.c and the vx-share subdirectory contain a remote interface for the
 415 VxWorks realtime kernel, which communicates over TCP using the Sun
 416 RPC library.  This would be a useful starting point for other remote-
 417 via-ethernet back ends.
 418
 419
 420                 Reporting Bugs
 421
 422 The correct address for reporting bugs found in gdb is
 423 "bug-gdb@prep.ai.mit.edu".  Please email all bugs to that address.
 424 Please include the GDB version number (e.g. gdb-4.4), and how
 425 you configured it (e.g. "sun4" or "mach386 host, i586-intel-synopsys
 426 target").
 427
 428 A known bug:
 429
 430   * If you run with a watchpoint enabled, breakpoints will become
 431     erratic and might not stop the program.  Disabling or deleting the
 432     watchpoint will fix the problem.
 433
 434 GDB can produce warnings about symbols that it does not understand.  By
 435 default, these warnings are disabled.  You can enable them by executing
 436 `set complaint 10' (which you can put in your ~/.gdbinit if you like).
 437 I recommend doing this if you are working on a compiler, assembler,
 438 linker, or gdb, since it will point out problems that you may be able
 439 to fix.  Warnings produced during symbol reading indicate some mismatch
 440 between the object file and GDB's symbol reading code.  In many cases,
 441 it's a mismatch between the specs for the object file format, and what
 442 the compiler actually outputs or the debugger actually understands.
 443
 444 If you port gdb to a new machine, please send the required changes to
 445 bug-gdb@prep.ai.mit.edu.  There's lots of information about doing your
 446 own port in the file gdb-4.4/gdb/doc/gdbint.texinfo, which you can
 447 print out, or read with `info' (see the Makefile.in there).  If your
 448 changes are more than a few lines, obtain and send in a copyright
 449 assignment from gnu@prep.ai.mit.edu, as described in the section
 450 `Writing Code for GDB'.
 451
 452
 453                 X Windows versus GDB
 454
 455 xgdb is obsolete.  We are not doing any development or support of it.
 456
 457 There is an "xxgdb", which shows more promise, which was posted to
 458 comp.sources.x.
 459
 460 For those intersted in auto display of source and the availability of
 461 an editor while debugging I suggest trying gdb-mode in gnu-emacs
 462 (Try typing M-x gdb RETURN).  Comments on this mode are welcome.
 463
 464
 465                 Writing Code for GDB
 466
 467 We appreciate having users contribute code that is of general use, but
 468 for it to be included in future GDB releases it must be cleanly
 469 written.  We do not want to include changes that will needlessly make
 470 future maintainance difficult.  It is not much harder to do things
 471 right, and in the long term it is worth it to the GNU project, and
 472 probably to you individually as well.
 473
 474 If you make substantial changes, you'll have to file a copyright
 475 assignment with the Free Software Foundation before we can produce a
 476 release that includes your changes.  Send mail requesting the copyright
 477 assignment to gnu@prep.ai.mit.edu.  Do this early, like before the
 478 changes actually work, or even before you start them, because a manager
 479 or lawyer on your end will probably make this a slow process.
 480
 481 Please code according to the GNU coding standards.  If you do not have
 482 a copy, you can request one by sending mail to gnu@prep.ai.mit.edu.
 483
 484 Please try to avoid making machine-specific changes to
 485 machine-independent files.  If this is unavoidable, put a hook in the
 486 machine-independent file which calls a (possibly) machine-dependent
 487 macro (for example, the IGNORE_SYMBOL macro can be used for any
 488 symbols which need to be ignored on a specific machine.  Calling
 489 IGNORE_SYMBOL in dbxread.c is a lot cleaner than a maze of #if
 490 defined's).  The machine-independent code should do whatever "most"
 491 machines want if the macro is not defined in param.h.  Using #if
 492 defined can sometimes be OK (e.g. SET_STACK_LIMIT_HUGE) but should be
 493 conditionalized on a specific feature of an operating system (set in
 494 tm.h or xm.h) rather than something like #if defined(vax) or #if
 495 defined(SYSV).  If you use an #ifdef on some symbol that is defined
 496 in a header file (e.g. #ifdef TIOCSETP), *please* make sure that you
 497 have #include'd the relevant header file in that module!
 498
 499 It is better to replace entire routines which may be system-specific,
 500 rather than put in a whole bunch of hooks which are probably not going
 501 to be helpful for any purpose other than your changes.  For example,
 502 if you want to modify dbxread.c to deal with DBX debugging symbols
 503 which are in COFF files rather than BSD a.out files, do something
 504 along the lines of a macro GET_NEXT_SYMBOL, which could have
 505 different definitions for COFF and a.out, rather than trying to put
 506 the necessary changes throughout all the code in dbxread.c that
 507 currently assumes BSD format.
 508
 509 When generalizing GDB along a particular interface, please use an
 510 attribute-struct rather than inserting tests or switch statements
 511 everywhere.  For example, GDB has been generalized to handle multiple
 512 kinds of remote interfaces -- not by #ifdef's everywhere, but by
 513 defining the "target_ops" structure and having a current target (as
 514 well as a stack of targets below it, for memory references).  Whenever
 515 something needs to be done that depends on which remote interface we
 516 are using, a flag in the current target_ops structure is tested (e.g.
 517 `target_has_stack'), or a function is called through a pointer in the
 518 current target_ops structure.  In this way, when a new remote interface
 519 is added, only one module needs to be touched -- the one that actually
 520 implements the new remote interface.  Other examples of
 521 attribute-structs are BFD access to multiple kinds of object file
 522 formats, or GDB's access to multiple source languages.
 523
 524 Please avoid duplicating code.  For example, in GDB 3.x all the stuff
 525 in infptrace.c was duplicated in *-dep.c, and so changing something
 526 was very painful.  In GDB 4.x, these have all been consolidated
 527 into infptrace.c.  infptrace.c can deal with variations between
 528 systems the same way any system-independent file would (hooks, #if
 529 defined, etc.), and machines which are radically different don't need
 530 to use infptrace.c at all.  The same was true of core_file_command
 531 and exec_file_command.
 532
 533
 534                 Debugging gdb with itself
 535
 536 If gdb is limping on your machine, this is the preferred way to get it
 537 fully functional.  Be warned that in some ancient Unix systems, like
 538 Ultrix 4.0, a program can't be running in one process while it is being
 539 debugged in another.  Rather than doing "./gdb ./gdb", which works on
 540 Suns and such, you can copy gdb to gdb2 and then do "./gdb ./gdb2".
 541
 542 When you run gdb in the gdb source directory, it will read a ".gdbinit"
 543 file that sets up some simple things to make debugging gdb easier.  The
 544 "info" command, when executed without a subcommand in a gdb being
 545 debugged by gdb, will pop you back up to the top level gdb.  See
 546 .gdbinit for details.
 547
 548 I strongly recommend printing out the reference card and using it.
 549 Send reference-card suggestions to bug-gdb@prep.ai.mit.edu, just like bugs.
 550
 551 If you use emacs, you will probably want to do a "make TAGS" after you
 552 configure your distribution; this will put the machine dependent
 553 routines for your local machine where they will be accessed first by a
 554 M-period.
 555
 556 Also, make sure that you've either compiled gdb with your local cc, or
 557 have run `fixincludes' if you are compiling with gcc.
 558 \f
 559 (this is for editing this file with GNU emacs)
 560 Local Variables:
 561 mode: text
 562 End: