gdb/README

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