gdb/README

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