gdb/README

   1 This is GDB, the GNU source-level debugger, presently running under
   2 un*x.  This is a pre-alpha version of GDB version 4, and has NOT been
   3 extensively tested.  It surely has some bugs, both bugs that were
   4 present in version 3 and new bugs.  I have filed all the bug reports
   5 and fixes mailed to bug-gdb, and the fixes in particular will move
   6 into these sources as I find the time.
   7
   8               => THIS VERSION IS FRAGILE! <=
   9
  10         It depends on preliminary versions of a new "binary file
  11         descriptor" library, a new global "include" directory,
  12         and separate libraries for "readline" and "libiberty", which
  13         are packaged separately from GDB.  You must obtain, configure
  14         and build these libraries manually, then configure and build gdb.
  15         When building gdb's for multiple platforms, you must manually
  16         rebuild the libraries separately for each platform.  Yes, of
  17         course, we are working on this!  FIXME!
  18
  19         Configure and build the libraries for your host system by:
  20
  21                 cd ../bfd
  22                 ./configure HOSTNAME
  23                 make
  24
  25                 cd ../libiberty
  26                 ./configure HOSTNAME
  27                 make
  28
  29                 cd ../readline
  30                 [edit Makefile as appropriate]
  31                 make
  32
  33         Then you can cd ../gdb-whatever, and config and build gdb.
  34
  35 This release moves the generic GNU include files, the BFD library, the
  36 getopt routines, obstacks, and the readline library into the parent
  37 directory of gdb.  The idea is that a variety of GNU tools can share a
  38 common copy of these things.
  39
  40 A summary of features new since gdb-3.5 is in the file `WHATS.NEW'.
  41
  42 The best way to build GDB, in my opinion, is in a subdirectory.  I use
  43 a naming convention "=XXX" where XXX is the machine type I'm building
  44 for.  Nothing depends on this, it's just how I remember which
  45 subdirectories are what.  So, once you have the BFD library built for
  46 that machine, you can do:
  47
  48         cd gdb-x.yy     (the directory where this README is)
  49         mkdir =XXX      (e.g. mkdir =vax)
  50         cd =XXX
  51         ../config.gdb machine
  52         make
  53
  54 Machine is like "vax" or "sun4".  For more information type `../config.gdb'.
  55
  56 Once you have done that, just `make' will do everything, producing an
  57 executable `gdb' in this directory.
  58
  59 You can also build gdb binaries in a completely different directory from its
  60 sources, by specifying "srcdir=YYY" to config.gdb, giving it an absolute
  61 or relative path to the source directory.
  62
  63 GDB can be used as a cross-debugger, running on a machine of one type
  64 while debugging a program running on a machine of another type.  You
  65 configure it this way by specifying `config.gdb host target' where host
  66 is where GDB runs, and target is where your program runs.
  67
  68 If you want a new (current to this release) version of the manual, you
  69 will have to use the gdb.texinfo and texinfo.tex files provided with
  70 this distribution.  For details see the texinfo manual (distributed
  71 with emacs and as a printed manual).
  72
  73 About languages other than C...
  74
  75 C++ support has been integrated into gdb.  GDB should work with FORTRAN
  76 programs.  (If you have problem, please send a bug report; note that you
  77 may have to refer to some FORTRAN variables with a trailing
  78 underscore).  I am not aware of anyone who is working on getting it
  79 to use the syntax of any language other than C or C++.  Pascal programs
  80 which use sets, subranges, file variables, or nested functions will not
  81 currently work.
  82
  83 About kernel debugging...
  84
  85 I have't done this myself so I can't really offer any advice.
  86 Remote debugging over serial lines is more like to be in a currently
  87 functioning state than the standalone gdb (kdb).  FIXME.
  88
  89 About remote debugging...
  90
  91 [This section seems to be out of date, I have never seen the "rapp"
  92 program, though I would like to.  FIXME.]
  93 `rapp' runs under unix and acts as a remote stub (like rem-multi.shar
  94 distributed with GDB version 3).  Currently it just works over UDP
  95 (network), not over a serial line.  To get it running
  96 * Compile GDB on the host machine as usual
  97 * Compile rapp on the target machine, giving for both host and target
  98   the type of the target machine
  99 * Install "gdb" in /etc/services on both machines.
 100
 101 This will get reworked before the initial release of 4.x.  FIXME.
 102
 103 The files m68k-stub.c and i386-stub.c contain two examples of remote
 104 stubs to be used with remote.c.  They are designeded to run standalone
 105 on a 68k or 386 cpu and communicate properly with the remote.c stub
 106 over a serial line.
 107
 108 The file rem-multi.shar contains a general stub that can probably be
 109 running on various different flavors of unix to allow debugging over a
 110 serial line from one machine to another.
 111
 112 The files remote-eb.c and remote-nindy.c are two examples of remote
 113 interfaces for talking to existing ROM monitors (for the AMD 29000 and the
 114 Intel 960 repsectively).  There is also a remote interface for the
 115 VxWorks realtime kernel, which communicates over TCP/IP, in remote-vx.c
 116 and the vx-share subdirectory.
 117
 118 About reporting bugs...
 119
 120 The correct address for reporting bugs found with gdb is
 121 "bug-gdb@prep.ai.mit.edu".  Please email all bugs to that address.
 122
 123 About xgdb...
 124
 125 xgdb is obsolete.  We are not doing any development or support of it.
 126
 127 There is an "xxgdb", which shows more promise.
 128
 129 For those intersted in auto display of source and the availability of
 130 an editor while debugging I suggest trying gdb-mode in gnu-emacs
 131 (Try typing M-x gdb RETURN).  Comments on this mode are welcome.
 132
 133 About the machine-dependent files...
 134
 135 tconfig/<machine>
 136 This contains Makefile stuff for when the target system is <machine>.
 137 It also specifies the name of the tm-XXX.h file for this machine.
 138
 139 xconfig/<machine>
 140 This contains Makefile stuff for when the host system is <machine>.
 141 It also specifies the name of the xm-XXX.h file for this machine.
 142
 143 tm-XXX.h (tm.h is a link to this file, created by config.gdb).
 144 This file contains macro definitions that express information
 145 about the target machine's registers, stack frame format and instructions.
 146
 147 xm-XXX.h (xm.h is a link to this file, created by config.gdb).
 148 This contains macro definitions describing the host system environment,
 149 such as byte order, host C compiler and library, ptrace support,
 150 and core file structure.
 151
 152 <machine>-opcode.h
 153 <machine>-pinsn.c
 154 These files contain the information necessary to print instructions
 155 for your cpu type.  <machine>-opcode.h includes some large initialized
 156 data structures, which is strange for a ".h" file, but it's OK since
 157 it is only included in one place.  <machine>-opcode.h is shared
 158 between the debugger and the assembler (if the GNU assembler has been
 159 ported to that machine), whereas <machine>-pinsn.c is specific to GDB.
 160
 161 <machine>-tdep.c
 162 This file contains any miscellaneous code required for this machine
 163 as a target.  On some machines it doesn't exist at all.  Its existence
 164 is specified in the tconfig/XXX file.
 165
 166 <machine>-xdep.c
 167 This file contains any miscellaneous code required for this machine
 168 as a host.  On some machines it doesn't exist at all.  Its existence
 169 is specified in the xconfig/XXX file.
 170
 171 infptrace.c
 172 This is the low level interface to inferior processes for systems
 173 using the Unix ptrace call in a vanilla way.  Some systems have their
 174 own routines in <machine>-xdep.c.  Whether or not it is used
 175 is specified in the xconfig/XXX file.
 176
 177 coredep.c
 178 Machine and system-dependent aspects of reading core files.  Some
 179 machines use coredep.c; some have the routines in <machine>-xdep.c.
 180 Whether or not it is used is specified in the xconfig/XXX file.
 181 Now that BFD is used to read core files, virtually all machines should
 182 use coredep.c and should just provide fetch_core_registers in
 183 <machine>-xdep.c.
 184
 185 exec.c
 186 Machine and system-dependent aspects of reading executable files.
 187 Some machines use exec.c; some have the routines in <machine>-tdep.c
 188 Since BFD, virtually all machines should use exec.c.
 189
 190 About writing code for GDB...
 191
 192 We appreciate having users contribute code that is of general use, but
 193 for it to be included in future GDB releases it must be cleanly
 194 written.  We do not want to include changes that will needlessly make
 195 future maintainance difficult.  It is not much harder to do things
 196 right, and in the long term it is worth it to the GNU project, and
 197 probably to you individually as well.
 198
 199 Please code according to the GNU coding standards.  If you do not have
 200 a copy, you can request one by sending mail to gnu@prep.ai.mit.edu.
 201
 202 If you make substantial changes, you'll have to file a copyright
 203 assignment with the Free Software Foundation before we can produce a
 204 release that includes your changes.  Send mail requesting the copyright
 205 assignment to gnu@prep.ai.mit.edu.  Do this early, like before the
 206 changes actually work, or even before you start them, because a manager
 207 or lawyer on your end will probably make this a slow process.
 208
 209 Please try to avoid making machine-specific changes to
 210 machine-independent files.  If this is unavoidable, put a hook in the
 211 machine-independent file which calls a (possibly) machine-dependent
 212 macro (for example, the IGNORE_SYMBOL macro can be used for any
 213 symbols which need to be ignored on a specific machine.  Calling
 214 IGNORE_SYMBOL in dbxread.c is a lot cleaner than a maze of #if
 215 defined's).  The machine-independent code should do whatever "most"
 216 machines want if the macro is not defined in param.h.  Using #if
 217 defined can sometimes be OK (e.g. SET_STACK_LIMIT_HUGE) but should be
 218 conditionalized on a specific feature of an operating system (set in
 219 tm.h or xm.h) rather than something like #if defined(vax) or #if
 220 defined(SYSV).  If you use an #ifdef on some symbol that is defined
 221 in a header file (e.g. #ifdef TIOCSETP), *please* make sure that you
 222 have #include'd the relevant header file in that module!
 223
 224 It is better to replace entire routines which may be system-specific,
 225 rather than put in a whole bunch of hooks which are probably not going
 226 to be helpful for any purpose other than your changes.  For example,
 227 if you want to modify dbxread.c to deal with DBX debugging symbols
 228 which are in COFF files rather than BSD a.out files, do something
 229 along the lines of a macro GET_NEXT_SYMBOL, which could have
 230 different definitions for COFF and a.out, rather than trying to put
 231 the necessary changes throughout all the code in dbxread.c that
 232 currently assumes BSD format.
 233
 234 Please avoid duplicating code.  For example, in GDB 3.x all the stuff
 235 in infptrace.c was duplicated in *-dep.c, and so changing something
 236 was very painful.  Thus in GDB 4.x these have all been consolidated
 237 into infptrace.c.  infptrace.c can deal with variations between
 238 systems the same way any system-independent file would (hooks, #if
 239 defined, etc.), and machines which are radically different don't need
 240 to use infptrace.c at all.  The same was true of core_file_command
 241 and exec_file_command.
 242
 243 About debugging gdb with itself...
 244
 245 You probably want to do a "make TAGS" after you configure your
 246 distribution; this will put the machine dependent routines for your
 247 local machine where they will be accessed first by a M-period .
 248
 249 Also, make sure that you've compiled gdb with your local cc or taken
 250 appropriate precautions regarding ansification of include files.  See
 251 the Makefile for more information.
 252
 253 When you run gdb in this directory, it will read a ".gdbinit" file that
 254 sets up some simple things to make debugging gdb easier.  The "info"
 255 command, when executed without a subcommand in a gdb being debugged by
 256 gdb, will pop you back up to the top level gdb.  See .gdbinit for details.
 257 \f
 258 (this is for editing this file with GNU emacs)
 259 Local Variables:
 260 mode: text
 261 End: