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