gdb/README

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