This commit was generated by cvs2svn to track changes on a CVS vendor
[external/binutils.git] / gdb / README
1                      README for gdb-4.18 release
2                    Updated 4 Apr 1999 by Jim Blandy
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-4.18 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-4.18.tar.gz file, you'll find a directory
27 called `gdb-4.18', which contains:
28
29   COPYING          config.sub*      libiberty/       opcodes/
30   COPYING.LIB      configure*       mmalloc/         readline/
31   Makefile.in      configure.in     move-if-change*  sim/
32   README           etc/             mpw-README       texinfo/
33   bfd/             gdb/             mpw-build.in     utils/
34   config/          include/         mpw-config.in
35   config.guess*    install.sh*      mpw-configure
36
37 To build GDB, you can just do:
38
39         cd gdb-4.18
40         ./configure
41         make
42         cp gdb/gdb /usr/local/bin/gdb   (or wherever you want)
43
44 This will configure and build all the libraries as well as GDB.
45 If `configure' can't determine your system type, specify one as its
46 argument, e.g., sun4 or decstation.
47
48 If you get compiler warnings during this stage, see the `Reporting Bugs'
49 section below; there are a few known problems.
50
51 GDB requires an ANSI C compiler.  If you do not have an ANSI C
52 compiler for your system, you may be able to download and install the
53 GNU CC compiler.  It is available via anonymous FTP from ftp.gnu.org,
54 in /pub/gnu/gcc (as a URL, that's ftp://ftp.gnu.org/pub/gnu/gcc).
55
56 GDB can be used as a cross-debugger, running on a machine of one type
57 while debugging a program running on a machine of another type.  See below.
58
59
60 More Documentation
61 ******************
62
63    All the documentation for GDB comes as part of the machine-readable
64 distribution.  The documentation is written in Texinfo format, which is
65 a documentation system that uses a single source file to produce both
66 on-line information and a printed manual.  You can use one of the Info
67 formatting commands to create the on-line version of the documentation
68 and TeX (or `texi2roff') to typeset the printed version.
69
70    GDB includes an already formatted copy of the on-line Info version of
71 this manual in the `gdb/doc' subdirectory.  The main Info file is
72 `gdb-4.18/gdb/doc/gdb.info', and it refers to subordinate files matching
73 `gdb.info*' in the same directory.  If necessary, you can print out
74 these files, or read them with any editor; but they are easier to read
75 using the `info' subsystem in GNU Emacs or the standalone `info' program,
76 available as part of the GNU Texinfo distribution.
77
78    If you want to format these Info files yourself, you need one of the
79 Info formatting programs, such as `texinfo-format-buffer' or
80 `makeinfo'.
81
82    If you have `makeinfo' installed, and are in the top level GDB
83 source directory (`gdb-4.18', in the case of version 4.18), you can make
84 the Info file by typing:
85
86      cd gdb/doc
87      make info
88
89    If you want to typeset and print copies of this manual, you need
90 TeX, a program to print its DVI output files, and `texinfo.tex', the
91 Texinfo definitions file.  This file is included in the GDB
92 distribution, in the directory `gdb-4.18/texinfo'.
93
94    TeX is a typesetting program; it does not print files directly, but
95 produces output files called DVI files.  To print a typeset document,
96 you need a program to print DVI files.  If your system has TeX
97 installed, chances are it has such a program.  The precise command to
98 use depends on your system; `lpr -d' is common; another (for PostScript
99 devices) is `dvips'.  The DVI print command may require a file name
100 without any extension or a `.dvi' extension.
101
102    TeX also requires a macro definitions file called `texinfo.tex'. 
103 This file tells TeX how to typeset a document written in Texinfo
104 format.  On its own, TeX cannot read, much less typeset a Texinfo file.
105  `texinfo.tex' is distributed with GDB and is located in the
106 `gdb-4.18/texinfo' directory.
107
108    If you have TeX and a DVI printer program installed, you can typeset
109 and print this manual.  First switch to the the `gdb' subdirectory of
110 the main source directory (for example, to `gdb-4.18/gdb') and then type:
111
112      make gdb.dvi
113
114
115 Installing GDB
116 **************
117
118    GDB comes with a `configure' script that automates the process of
119 preparing GDB for installation; you can then use `make' to build the
120 `gdb' program.
121
122    The GDB distribution includes all the source code you need for GDB in
123 a single directory, whose name is usually composed by appending the
124 version number to `gdb'.
125
126    For example, the GDB version 4.18 distribution is in the `gdb-4.18'
127 directory.  That directory contains:
128
129 `gdb-4.18/{COPYING,COPYING.LIB}'
130      Standard GNU license files.  Please read them.
131
132 `gdb-4.18/bfd'
133      source for the Binary File Descriptor library
134
135 `gdb-4.18/config*'
136      script for configuring GDB, along with other support files
137
138 `gdb-4.18/gdb'
139      the source specific to GDB itself
140
141 `gdb-4.18/include'
142      GNU include files
143
144 `gdb-4.18/libiberty'
145      source for the `-liberty' free software library
146
147 `gdb-4.18/mmalloc'
148      source for the GNU memory-mapped malloc package
149
150 `gdb-4.18/opcodes'
151      source for the library of opcode tables and disassemblers
152
153 `gdb-4.18/readline'
154      source for the GNU command-line interface
155      NOTE:  The readline library is compiled for use by GDB, but will
156      not be installed on your system when "make install" is issued.
157
158 `gdb-4.18/sim'
159      source for some simulators (ARM, D10V, SPARC, M32R, MIPS, PPC, V850, etc)
160
161 `gdb-4.18/intl'
162      source for the GNU gettext library, for internationalization.
163      This is slightly modified from the standalone gettext
164      distribution you can get from GNU.
165
166 `gdb-4.18/texinfo'
167      The `texinfo.tex' file, which you need in order to make a printed
168      manual using TeX.
169
170 `gdb-4.18/etc'
171      Coding standards, useful files for editing GDB, and other
172      miscellanea.
173
174 `gdb-4.18/utils'
175      A grab bag of random utilities.
176
177
178    The simplest way to configure and build GDB is to run `configure'
179 from the `gdb-VERSION-NUMBER' source directory, which in this example
180 is the `gdb-4.18' directory.
181
182    First switch to the `gdb-VERSION-NUMBER' source directory if you are
183 not already in it; then run `configure'.
184
185    For example:
186
187      cd gdb-4.18
188      ./configure
189      make
190
191    Running `configure' followed by `make' builds the `bfd',
192 `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
193 The configured source files, and the binaries, are left in the
194 corresponding source directories.
195
196    `configure' is a Bourne-shell (`/bin/sh') script; if your system
197 does not recognize this automatically when you run a different shell,
198 you may need to run `sh' on it explicitly:
199
200      sh configure
201
202    If you run `configure' from a directory that contains source
203 directories for multiple libraries or programs, such as the `gdb-4.18'
204 source directory for version 4.18, `configure' creates configuration
205 files for every directory level underneath (unless you tell it not to,
206 with the `--norecursion' option).
207
208    You can run the `configure' script from any of the subordinate
209 directories in the GDB distribution, if you only want to configure that
210 subdirectory; but be sure to specify a path to it.
211
212    For example, with version 4.18, type the following to configure only
213 the `bfd' subdirectory:
214
215      cd gdb-4.18/bfd
216      ../configure
217
218    You can install `gdb' anywhere; it has no hardwired paths. However,
219 you should make sure that the shell on your path (named by the `SHELL'
220 environment variable) is publicly readable.  Remember that GDB uses the
221 shell to start your program--some systems refuse to let GDB debug child
222 processes whose programs are not readable.
223
224
225 Compiling GDB in another directory
226 ==================================
227
228    If you want to run GDB versions for several host or target machines,
229 you need a different `gdb' compiled for each combination of host and
230 target.  `configure' is designed to make this easy by allowing you to
231 generate each configuration in a separate subdirectory, rather than in
232 the source directory.  If your `make' program handles the `VPATH'
233 feature correctly (GNU `make' and SunOS 'make' are two that should),
234 running `make' in each of these directories builds the `gdb' program
235 specified there.
236
237    To build `gdb' in a separate directory, run `configure' with the
238 `--srcdir' option to specify where to find the source. (You also need
239 to specify a path to find `configure' itself from your working
240 directory.  If the path to `configure' would be the same as the
241 argument to `--srcdir', you can leave out the `--srcdir' option; it
242 will be assumed.)
243
244    For example, with version 4.18, you can build GDB in a separate
245 directory for a Sun 4 like this:
246
247      cd gdb-4.18
248      mkdir ../gdb-sun4
249      cd ../gdb-sun4
250      ../gdb-4.18/configure sun4
251      make
252
253    When `configure' builds a configuration using a remote source
254 directory, it creates a tree for the binaries with the same structure
255 (and using the same names) as the tree under the source directory.  In
256 the example, you'd find the Sun 4 library `libiberty.a' in the
257 directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
258
259    One popular reason to build several GDB configurations in separate
260 directories is to configure GDB for cross-compiling (where GDB runs on
261 one machine--the host--while debugging programs that run on another
262 machine--the target).  You specify a cross-debugging target by giving
263 the `--target=TARGET' option to `configure'.
264
265    When you run `make' to build a program or library, you must run it
266 in a configured directory--whatever directory you were in when you
267 called `configure' (or one of its subdirectories).
268
269    The `Makefile' that `configure' generates in each source directory
270 also runs recursively.  If you type `make' in a source directory such
271 as `gdb-4.18' (or in a separate configured directory configured with
272 `--srcdir=PATH/gdb-4.18'), you will build all the required libraries,
273 and then build GDB.
274
275    When you have multiple hosts or targets configured in separate
276 directories, you can run `make' on them in parallel (for example, if
277 they are NFS-mounted on each of the hosts); they will not interfere
278 with each other.
279
280
281 Specifying names for hosts and targets
282 ======================================
283
284    The specifications used for hosts and targets in the `configure'
285 script are based on a three-part naming scheme, but some short
286 predefined aliases are also supported.  The full naming scheme encodes
287 three pieces of information in the following pattern:
288
289      ARCHITECTURE-VENDOR-OS
290
291    For example, you can use the alias `sun4' as a HOST argument or in a
292 `--target=TARGET' option.  The equivalent full name is
293 `sparc-sun-sunos4'.
294
295    The `configure' script accompanying GDB does not provide any query
296 facility to list all supported host and target names or aliases. 
297 `configure' calls the Bourne shell script `config.sub' to map
298 abbreviations to full names; you can read the script, if you wish, or
299 you can use it to test your guesses on abbreviations--for example:
300
301      % sh config.sub sun4
302      sparc-sun-sunos4.1.1
303      % sh config.sub sun3
304      m68k-sun-sunos4.1.1
305      % sh config.sub decstation
306      mips-dec-ultrix4.2
307      % sh config.sub hp300bsd
308      m68k-hp-bsd
309      % sh config.sub i386v
310      i386-pc-sysv
311      % sh config.sub i786v
312      Invalid configuration `i786v': machine `i786v' not recognized
313
314 `config.sub' is also distributed in the GDB source directory
315 (`gdb-4.18', for version 4.18).
316
317
318 `configure' options
319 ===================
320
321    Here is a summary of the `configure' options and arguments that are
322 most often useful for building GDB.  `configure' also has several other
323 options not listed here.  *note : (configure.info)What Configure Does,
324 for a full explanation of `configure'.
325
326      configure [--help]
327                [--prefix=DIR]
328                [--srcdir=PATH]
329                [--norecursion] [--rm]
330                [--enable-build-warnings]
331                [--target=TARGET]
332                [--host=HOST]
333                [HOST]
334
335 You may introduce options with a single `-' rather than `--' if you
336 prefer; but you may abbreviate option names if you use `--'.
337
338 `--help'
339      Display a quick summary of how to invoke `configure'.
340
341 `-prefix=DIR'
342      Configure the source to install programs and files under directory
343      `DIR'.
344
345 `--srcdir=PATH'
346      *Warning: using this option requires GNU `make', or another `make'
347      that compatibly implements the `VPATH' feature.*
348      Use this option to make configurations in directories separate
349      from the GDB source directories.  Among other things, you can use
350      this to build (or maintain) several configurations simultaneously,
351      in separate directories.  `configure' writes configuration
352      specific files in the current directory, but arranges for them to
353      use the source in the directory PATH.  `configure' will create
354      directories under the working directory in parallel to the source
355      directories below PATH.
356
357 `--norecursion'
358      Configure only the directory level where `configure' is executed;
359      do not propagate configuration to subdirectories.
360
361 `--rm'
362      Remove the configuration that the other arguments specify.
363
364 `--enable-build-warnings'
365      When building the GDB sources, ask the compiler to warn about any
366      code which looks even vaguely suspicious.  You should only using
367      this feature if you're compiling with GNU CC.  It passes the
368      following flags:
369         -Wall
370         -Wpointer-arith
371         -Wstrict-prototypes
372         -Wmissing-prototypes
373         -Wmissing-declarations
374
375 `--target=TARGET'
376      Configure GDB for cross-debugging programs running on the specified
377      TARGET.  Without this option, GDB is configured to debug programs
378      that run on the same machine (HOST) as GDB itself.
379
380      There is no convenient way to generate a list of all available
381      targets.
382
383 `--host=HOST'
384      Configure GDB to run on the specified HOST.
385
386      There is no convenient way to generate a list of all available
387      hosts.
388
389 `HOST ...'
390      Same as `--host=HOST'.  If you omit this, GDB will guess; it's
391      quite accurate.
392
393 `configure' accepts other options, for compatibility with configuring
394 other GNU tools recursively; but these are the only options that affect
395 GDB or its supporting libraries.
396
397
398 Languages other than C
399 =======================
400
401 See the GDB manual (gdb/doc/gdb.texinfo) for information on this.
402
403
404 Kernel debugging
405 =================
406
407 I have't done this myself so I can't really offer any advice.
408 Remote debugging over serial lines works fine, but the kernel debugging
409 code in here has not been tested in years.  Van Jacobson has
410 better kernel debugging, but the UC lawyers won't let FSF have it.
411
412
413 Remote debugging
414 =================
415
416 The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples of
417 remote stubs to be used with remote.c.  They are designed to run
418 standalone on an m68k, i386, or SPARC cpu and communicate properly with
419 the remote.c stub over a serial line.
420
421 The directory gdb/gdbserver/ contains `gdbserver', a program that
422 allows remote debugging for Unix applications.  gdbserver is only
423 supported for some native configurations, including Sun 3, Sun 4,
424 and Linux.
425
426 There are a number of remote interfaces for talking to existing ROM
427 monitors and other hardware:
428
429         remote-adapt.c   AMD 29000 "Adapt"
430         remote-array.c   Array Tech RAID controller
431         remote-bug.c     Motorola BUG monitor
432         remote-d10v.c    GDB protocol, talking to a d10v chip
433         remote-e7000.c   Hitachi E7000 ICE
434         remote-eb.c      AMD 29000 "EBMON"
435         remote-es.c      Ericsson 1800 monitor
436         remote-est.c     EST emulator
437         remote-hms.c     Hitachi Micro Systems H8/300 monitor
438         remote-mips.c    MIPS remote debugging protocol
439         remote-mm.c      AMD 29000 "minimon"
440         remote-nindy.c   Intel 960 "Nindy"
441         remote-nrom.c    NetROM ROM emulator
442         remote-os9k.c    PC running OS/9000
443         remote-rdi.c     ARM with Angel monitor
444         remote-rdp.c     ARM with Demon monitor
445         remote-sds.c     PowerPC SDS monitor
446         remote-sim.c     Generalized simulator protocol
447         remote-st.c      Tandem ST-2000 monitor
448         remote-udi.c     AMD 29000 using the AMD "Universal Debug Interface"
449         remote-vx.c      VxWorks realtime kernel
450
451 Remote-vx.c and the vx-share subdirectory contain a remote interface for the
452 VxWorks realtime kernel, which communicates over TCP using the Sun
453 RPC library.  This would be a useful starting point for other remote-
454 via-ethernet back ends.
455
456 Remote-udi.c and the 29k-share subdirectory contain a remote interface
457 for AMD 29000 programs, which uses the AMD "Universal Debug Interface".
458 This allows GDB to talk to software simulators, emulators, and/or bare
459 hardware boards, via network or serial interfaces.  Note that GDB only
460 provides an interface that speaks UDI, not a complete solution.  You
461 will need something on the other end that also speaks UDI.
462
463
464 Reporting Bugs
465 ===============
466
467 The correct address for reporting bugs found in gdb is
468 "bug-gdb@gnu.org".  Please email all bugs, and all requests for
469 help with GDB, to that address.  Please include the GDB version number
470 (e.g., gdb-4.18), and how you configured it (e.g., "sun4" or "mach386
471 host, i586-intel-synopsys target").  Since GDB now supports so many
472 different configurations, it is important that you be precise about this.
473 If at all possible, you should include the actual banner that GDB prints
474 when it starts up, or failing that, the actual configure command that
475 you used when configuring GDB.
476
477 For more information on how/whether to report bugs, see the GDB Bugs
478 section of the GDB manual (gdb/doc/gdb.texinfo).
479
480 Known bugs:
481
482   * Under Ultrix 4.2 (DECstation-3100) or Alphas under OSF/1, we have
483     seen problems with backtraces after interrupting the inferior out
484     of a read().  The problem is caused by ptrace() returning an
485     incorrect value for the frame pointer register (register 15 or
486     30).  As far as we can tell, this is a kernel problem.  Any help
487     with this would be greatly appreciated.
488
489   * Under Ultrix 4.4 (DECstation-3100), setting the TERMCAP environment
490     variable to a string without a trailing ':' can cause GDB to dump
491     core upon startup.  Although the core file makes it look as though
492     GDB code failed, the crash actually occurs within a call to the
493     termcap library function tgetent().  The problem can be solved by
494     using the GNU Termcap library.
495
496     Alphas running OSF/1 (versions 1.0 through 2.1) have the same buggy
497     termcap code, but GDB behaves strangely rather than crashing.
498
499   * On DECstations there are warnings about shift counts out of range in
500     various BFD modules.  None of them is a cause for alarm, they are actually
501     a result of bugs in the DECstation compiler.
502
503   * Notes for the DEC Alpha using OSF/1:
504     The debugging output of native cc has two known problems; we view these
505     as compiler bugs.
506     The linker miscompacts symbol tables, which causes gdb to confuse the
507     type of variables or results in `struct <illegal>' type outputs.
508     dbx has the same problems with those executables.  A workaround is to
509     specify -Wl,-b when linking, but that will increase the executable size
510     considerably.
511     If a structure has incomplete type in one file (e.g., "struct foo *"
512     without a definition for "struct foo"), gdb will be unable to find the
513     structure definition from another file.
514     It has been reported that the Ultrix 4.3A compiler on decstations has the
515     same problems.
516
517   * Notes for Solaris 2.x, using the SPARCworks cc compiler:
518     You have to compile your program with the -xs option of the SPARCworks
519     compiler to be able to debug your program with gdb.
520     Under Solaris 2.3 you also need patch 101409-03 (Jumbo linker patch).
521     Under Solaris 2.2, if you have patch 101052 installed, make sure
522     that it is at least at revision 101052-06.
523
524   * Under Irix 5 for SGIs, you must have installed the `compiler_dev.hdr'
525     subsystem that is on the IDO CD, otherwise you will get complaints
526     that certain files such as `/usr/include/syms.h' cannot be found.
527
528   * Notes for BSD/386:
529     To compile gdb-4.18 on BSD/386, you must run the configure script and
530     its subscripts with bash.  Here is an easy way to do this:
531
532         bash -c 'CONFIG_SHELL=/bin/bash ./configure'
533
534     (configure will report i386-unknown-bsd).  Then, compile with the
535     standard "make" command.
536
537 GDB can produce warnings about symbols that it does not understand.  By
538 default, these warnings are disabled.  You can enable them by executing
539 `set complaint 10' (which you can put in your ~/.gdbinit if you like).
540 I recommend doing this if you are working on a compiler, assembler,
541 linker, or GDB, since it will point out problems that you may be able
542 to fix.  Warnings produced during symbol reading indicate some mismatch
543 between the object file and GDB's symbol reading code.  In many cases,
544 it's a mismatch between the specs for the object file format, and what
545 the compiler actually outputs or the debugger actually understands.
546
547
548 X Windows versus GDB
549 =====================
550
551 You should check out DDD, the Data Display Debugger.  Here's the blurb
552 from the DDD web site, http://www.cs.tu-bs.de/softech/ddd:
553
554     The Data Display Debugger (DDD) is a popular graphical user
555     interface for command-line debuggers such as GDB, DBX, JDB, WDB,
556     XDB, the Perl debugger, and the Python debugger.  Besides ``usual''
557     front-end features such as viewing source texts, DDD has become
558     famous through its interactive graphical data display, where data
559     structures are displayed as graphs. A simple mouse click
560     dereferences pointers or views structure contents, updated each
561     time the program stops. Using DDD, you can reason about your
562     application by watching its data, not just by viewing it execute
563     lines of source code.
564
565 Emacs users will very likely enjoy the Grand Unified Debugger mode;
566 try typing `M-x gdb RET'.
567
568 Those interested in experimenting with a new kind of gdb-mode
569 should load gdb/gdba.el into GNU Emacs 19.25 or later.  Comments
570 on this mode are also welcome.
571
572
573 Writing Code for GDB
574 =====================
575
576 There is a lot of information about writing code for GDB in the
577 internals manual, distributed with GDB in gdb/doc/gdbint.texinfo.  You
578 can read it by hand, print it by using TeX and texinfo, or process it
579 into an `info' file for use with Emacs' info mode or the standalone
580 `info' program.
581
582 If you are pondering writing anything but a short patch, especially
583 take note of the information about copyrights in the node Submitting
584 Patches.  It can take quite a while to get all the paperwork done, so
585 we encourage you to start that process as soon as you decide you are
586 planning to work on something, or at least well ahead of when you
587 think you will be ready to submit the patches.
588
589
590 GDB Testsuite
591 =============
592
593 There is a DejaGNU based testsuite available for testing your newly
594 built GDB, or for regression testing GDBs with local modifications.
595
596 Running the testsuite requires the prior installation of DejaGNU,
597 which is generally available via ftp; you'll need a pretty recent
598 release.  Once DejaGNU is installed, you can run the tests in one of
599 two ways:
600
601   (1)   cd gdb-4.18/gdb         (assuming you also unpacked gdb)
602         make check
603
604 or
605
606   (2)   cd gdb-4.18/gdb/testsuite
607         make site.exp   (builds the site specific file)
608         runtest -tool gdb GDB=../gdb    (or GDB=<somepath> as appropriate)
609
610 The second method gives you slightly more control in case of problems with
611 building one or more test executables or if you are using the testsuite
612 'standalone', without it being part of the GDB source tree.
613
614 See the DejaGNU documentation for further details.
615
616 \f
617 (this is for editing this file with GNU emacs)
618 Local Variables:
619 mode: text
620 End: