gdb/README

   1 This is GDB, the GNU source-level debugger, presently running under un*x.
   2
   3 Before compiling GDB, you must tell GDB what kind of machine you are
   4 running on.  To do this, type `config.gdb machine', where machine is
   5 something like `vax' or `sun2'.  For a list of valid machine types,
   6 type `config.gdb'.
   7
   8 Normally config.gdb edits the makefile as necessary.  If you have to
   9 edit the makefile on a standard machine listed in config.gdb this
  10 should be considered a bug and reported as such.
  11
  12 Once these files are set up, just `make' will do everything,
  13 producing an executable `gdb' in this directory.
  14
  15 If you want a new (current to this release) version of the manual, you
  16 will have to use the gdb.texinfo file provided with this distribution.
  17 The gdb.texinfo file requires the texinfo-format-buffer command from
  18 emacs 18.55 or later.
  19
  20 About languages other than C...
  21
  22 C++ support has been integrated into gdb.  GDB should work with Pascal
  23 and FORTRAN programs, but I am not aware of anyone who is working on
  24 getting it to use the syntax of any language other than C or C++.
  25
  26 About -gg format...
  27
  28 Currently GDB version 3.x does *not* support GCC's -gg format.  This
  29 is because it is (in theory) has fast enough startup on dbx debugging
  30 format object files that -gg format is unnecessary (and hence
  31 undesirable, since it wastes space and processing power in gcc).  I
  32 would like to hear people's opinions on the amount of time currently
  33 spent in startup; is it fast enough?
  34
  35 About remote debugging...
  36
  37 The two files remote-multi.shar and remote-sa.m68k.shar contain two
  38 examples of a remote stub to be used with remote.c.  The the -multi
  39 file is a general stub that can probably be running on various
  40 different flavors of unix to allow debugging over a serial line from
  41 one machine to another.  The remote-sa.m68k.shar is designed to run
  42 standalone on a 68k type cpu and communicate properley with the
  43 remote.c stub over a serial line.
  44
  45 About reporting bugs...
  46
  47 The correct address for reporting bugs found with gdb is
  48 "bug-gdb@prep.ai.mit.edu".  Please send all bugs to that address.
  49
  50 About xgdb...
  51
  52 xgdb.c was provided to us by the user community; it is not an integral
  53 part of the gdb distribution.  The problem of providing visual
  54 debugging support on top of gdb is peripheral to the GNU project and
  55 (at least right now) we can't afford to put time into it.  So while we
  56 will be happy to incorporate user fixes to xgdb.c, we do not guarantee
  57 that it will work and we will not fix bugs reported in it.  Someone is
  58 working on writing a new XGDB, so improving (e.g. by fixing it so that
  59 it will work, if it doesn't currently) the current one is not worth it.
  60
  61 For those intersted in auto display of source and the availability of
  62 an editor while debugging I suggest trying gdb-mode in gnu-emacs.
  63 Comments on this mode are welcome.
  64
  65 About the machine-dependent files...
  66
  67 m-<machine>.h (param.h is a link to this file).
  68 This file contains macro definitions that express information
  69 about the machine's registers, stack frame format and instructions.
  70
  71 <machine>-opcode.h (opcode.h is a link to this file).
  72 <machine>-pinsn.c (pinsn.c is a link to this file).
  73 These files contain the information necessary to print instructions
  74 for your cpu type.
  75
  76 <machine>-dep.c (dep.c is a link to this file).
  77 Those routines which provide a low level interface to ptrace and which
  78 tend to be machine-dependent.  (The machine-independent routines are in
  79 `infrun.c' and `inflow.c')
  80
  81 About writing code for GDB...
  82
  83 We appreciate having users contribute code that is of general use, but
  84 for it to be included in future GDB releases it must be cleanly
  85 written.  We do not want to include changes that will needlessly make future
  86 maintainance difficult.  It is not much harder to do things right, and
  87 in the long term it is worth it to the GNU project, and probably to
  88 you individually as well.
  89
  90 Please code according to the GNU coding standards.  If you do not have
  91 a copy, you can request one by sending mail to gnu@prep.ai.mit.edu.
  92
  93 Please try to avoid making machine-specific changes to
  94 machine-independent files (i.e. all files except "param.h" and
  95 "dep.c".  "pinsn.c" and "opcode.h" are processor-specific but not
  96 operating system-dependent).  If this is unavoidable, put a hook in
  97 the machine-independent file which calls a (possibly)
  98 machine-dependent macro (for example, the IGNORE_SYMBOL macro can be
  99 used for any symbols which need to be ignored on a specific machine.
 100 Calling IGNORE_SYMBOL in dbxread.c is a lot cleaner than a maze of
 101 #if defined's).  The machine-independent code should do whatever "most"
 102 machines want if the macro is not defined in param.h.  Using #if defined
 103 can sometimes be OK (e.g.  SET_STACK_LIMIT_HUGE) but should usually be
 104 conditionalized on a specific feature of an operating system (set in
 105 param.h) rather than something like #if defined(vax) or #if defined(SYSV).
 106
 107 It is better to replace entire routines which may be system-specific,
 108 rather than put in a whole bunch of hooks which are probably not going
 109 to be helpful for any purpose other than your changes.  For example,
 110 if you want to modify dbxread.c to deal with DBX debugging symbols
 111 which are in COFF files rather than a.out files, do something
 112 along the lines of a macro GET_NEXT_SYMBOL, which could have
 113 different definitions for COFF and a.out, rather than trying to put
 114 the necessary changes throughout all the code in dbxread.c that
 115 currently assumes a.out format.
 116
 117 Please avoid duplicating code.  For example, if something needs to be
 118 changed in read_inferior_memory, it is very painful because there is a
 119 copy in every dep.c file.  The correct way to do this is to put the
 120 standard ptrace interfaces in a separate file ptrace.c, which is used
 121 by all systems which have ptrace.  ptrace.c would deal with variations
 122 between systems the same way any system-independent file would (hooks,
 123 #if defined, etc.).
 124
 125 About debugging gdb with itself...
 126
 127 You probably want to do a "make TAGS" after you configure your
 128 distribution; this will put the machine dependent routines for your
 129 local machine where they will be accessed first by a M-period .
 130
 131 Also, you want to make sure that gdb is not compiled with shared
 132 libraries on the Sun 4.  And you want to make sure that you've
 133 compiled gdb with your local cc or taken appropriate precautions
 134 regarding ansification of include files.  See the Makefile for more
 135 information.
 136
 137 The "info" command, when executed without a subcommand in a gdb being
 138 debugged by gdb, will pop you back up to the top level gdb.  See
 139 .gdbinit for more details.
 140