diff options
Diffstat (limited to 'gdb/README')
| -rw-r--r-- | gdb/README | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/gdb/README b/gdb/README new file mode 100644 index 00000000000..999db4a12f7 --- /dev/null +++ b/gdb/README @@ -0,0 +1,259 @@ +This is GDB, the GNU source-level debugger, presently running under +un*x. This is a pre-alpha version of GDB version 4, and has NOT been +extensively tested. It surely has some bugs, both bugs that were +present in version 3 and new bugs. I have filed all the bug reports +and fixes mailed to bug-gdb, and the fixes in particular will move +into these sources as I find the time. + + => THIS VERSION IS PARTICULARLY FRAGILE! <= + + It depends on a preliminary version of a new "binary file + descriptor" library and a new global "include" directory, which + are packaged separately from GDB. You must obtain, configure + and build this library manually, then configure and build gdb. + When building gdb's for multiple platforms, you must manually + rebuild the bfd library separately for each platform. Yes, of + course, we are working on this! FIXME! + + Configure bfd for your host system by: + + cd ../bfd + edit Makefile + make + + Then you can cd ../gdb-whatever, and config and build gdb. + +This release moves the generic GNU include files, the BFD library, +and the getopt routines into the parent directory of gdb. The idea +is that a variety of GNU tools can share a common copy of these things. + +A summary of features new since gdb-3.5 is in the file `WHATS.NEW'. + +The best way to build GDB, in my opinion, is in a subdirectory. I use +a naming convention "=XXX" where XXX is the machine type I'm building +for. Nothing depends on this, it's just how I remember which +subdirectories are what. So, once you have the BFD library built for +that machine, you can do: + + cd gdb-x.yy (the directory where this README is) + mkdir =XXX (e.g. mkdir =vax) + cd =XXX + ../config.gdb machine + make + +Machine is like "vax" or "sun4". For more information type `../config.gdb'. + +Once you have done that, just `make' will do everything, producing an +executable `gdb' in this directory. + +You can also build gdb binaries in a completely different directory from its +sources, by specifying "srcdir=YYY" to config.gdb, giving it an absolute +or relative path to the source directory. + +GDB can be used as a cross-debugger, running on a machine of one type +while debugging a program running on a machine of another type. You +configure it this way by specifying `config.gdb host target' where host +is where GDB runs, and target is where your program runs. + +If you want a new (current to this release) version of the manual, you +will have to use the gdb.texinfo file provided with this distribution. +For details see the texinfo manual (distributed with emacs and as a +printed manual). + +About languages other than C... + +C++ support has been integrated into gdb. GDB should work with FORTRAN +programs (if you have problem, please send a bug report; note that you +may have to refer to some FORTRAN variables with a trailing +underscore), but I am not aware of anyone who is working on getting it +to use the syntax of any language other than C or C++. Pascal programs +which use sets, subranges, file variables, or nested functions will not +currently work. + +About kernel debugging... + +I have't done this myself so I can't really offer any advice. +Remote debugging over serial lines is more like to be in a currently +functioning state than the standalone gdb (kdb). FIXME. + +About remote debugging... + +[This section seems to be out of date, I have never seen the "rapp" +program, though I would like to. FIXME.] +`rapp' runs under unix and acts as a remote stub (like remote-multi.shar +distributed with GDB version 3). Currently it just works over UDP +(network), not over a serial line. To get it running +* Compile GDB on the host machine as usual +* Compile rapp on the target machine, giving for both host and target + the type of the target machine +* Install "gdb" in /etc/services on both machines. + +This will get reworked before the initial release of 4.x. FIXME. + +The two files remote-multi.shar and remote-sa.m68k.shar contain two +examples of a remote stub to be used with remote.c. The the -multi +file is a general stub that can probably be running on various +different flavors of unix to allow debugging over a serial line from +one machine to another. The remote-sa.m68k.shar is designed to run +standalone on a 68k type cpu and communicate properley with the +remote.c stub over a serial line. + +The files remote-eb.c and remote-nindy.c are two examples of remote +interfaces for talking to existing ROM monitors (for the AMD 29000 and the +Intel 960 repsectively). There is also a remote interface for the +VxWorks realtime kernel, which communicates over TCP/IP, in remote-vx.c +and the vx-share subdirectory. + +About reporting bugs... + +The correct address for reporting bugs found with gdb is +"bug-gdb@prep.ai.mit.edu". Please email all bugs to that address. + +About xgdb... + +Hopefully a new xgdb will be in 4.x. + +xgdb.c was provided to us by the user community; it is not an integral +part of the gdb distribution. The problem of providing visual +debugging support on top of gdb is peripheral to the GNU project and +(at least right now) we can't afford to put time into it. So while we +will be happy to incorporate user fixes to xgdb.c, we do not guarantee +that it will work and we will not fix bugs reported in it. See +XGDB-README for one person's opinion about what is wrong with the +current xgdb. Someone is working on writing a new XGDB, so improving +(e.g. by fixing it so that it will work, if it doesn't currently) the +current one is not worth it. + +For those intersted in auto display of source and the availability of +an editor while debugging I suggest trying gdb-mode in gnu-emacs +(Try typing M-x gdb RETURN). Comments on this mode are welcome. + +About the machine-dependent files... + +tconfig/<machine> +This contains Makefile stuff for when the target system is <machine>. +It also specifies the name of the tm-XXX.h file for this machine. + +xconfig/<machine> +This contains Makefile stuff for when the host system is <machine>. +It also specifies the name of the xm-XXX.h file for this machine. + +tm-XXX.h (tm.h is a link to this file, created by config.gdb). +This file contains macro definitions that express information +about the target machine's registers, stack frame format and instructions. + +xm-XXX.h (xm.h is a link to this file, created by config.gdb). +This contains macro definitions describing the host system environment, +such as byte order, host C compiler and library, ptrace support, +and core file structure. + +<machine>-opcode.h +<machine>-pinsn.c +These files contain the information necessary to print instructions +for your cpu type. <machine>-opcode.h includes some large initialized +data structures, which is strange for a ".h" file, but it's OK since +it is only included in one place. <machine>-opcode.h is shared +between the debugger and the assembler (if the GNU assembler has been +ported to that machine), whereas <machine>-pinsn.c is specific to GDB. + +<machine>-tdep.c +This file contains any miscellaneous code required for this machine +as a target. On some machines it doesn't exist at all. Its existence +is specified in the tconfig/XXX file. + +<machine>-xdep.c +This file contains any miscellaneous code required for this machine +as a host. On some machines it doesn't exist at all. Its existence +is specified in the xconfig/XXX file. + +infptrace.c +This is the low level interface to inferior processes for systems +using the Unix ptrace call in a vanilla way. Some systems have their +own routines in <machine>-xdep.c. Whether or not it is used +is specified in the xconfig/XXX file. + +coredep.c +Machine and system-dependent aspects of reading core files. Some +machines use coredep.c; some have the routines in <machine>-xdep.c. +Whether or not it is used is specified in the xconfig/XXX file. +Now that BFD is used to read core files, virtually all machines should +use coredep.c and should just provide fetch_core_registers in +<machine>-xdep.c. + +exec.c +Machine and system-dependent aspects of reading executable files. +Some machines use exec.c; some have the routines in <machine>-tdep.c +Since BFD, virtually all machines should use exec.c. + +About writing code for GDB... + +We appreciate having users contribute code that is of general use, but +for it to be included in future GDB releases it must be cleanly +written. We do not want to include changes that will needlessly make +future maintainance difficult. It is not much harder to do things +right, and in the long term it is worth it to the GNU project, and +probably to you individually as well. + +Please code according to the GNU coding standards. If you do not have +a copy, you can request one by sending mail to gnu@prep.ai.mit.edu. + +If you make substantial changes, you'll have to file a copyright +assignment with the Free Software Foundation before we can produce a +release that includes your changes. Send mail requesting the copyright +assignment to gnu@prep.ai.mit.edu. Do this early, like before the +changes actually work, or even before you start them, because a manager +or lawyer on your end will probably make this a slow process. + +Please try to avoid making machine-specific changes to +machine-independent files. If this is unavoidable, put a hook in the +machine-independent file which calls a (possibly) machine-dependent +macro (for example, the IGNORE_SYMBOL macro can be used for any +symbols which need to be ignored on a specific machine. Calling +IGNORE_SYMBOL in dbxread.c is a lot cleaner than a maze of #if +defined's). The machine-independent code should do whatever "most" +machines want if the macro is not defined in param.h. Using #if +defined can sometimes be OK (e.g. SET_STACK_LIMIT_HUGE) but should be +conditionalized on a specific feature of an operating system (set in +tm.h or xm.h) rather than something like #if defined(vax) or #if +defined(SYSV). If you use an #ifdef on some symbol that is defined +in a header file (e.g. #ifdef TIOCSETP), *please* make sure that you +have #include'd the relevant header file in that module! + +It is better to replace entire routines which may be system-specific, +rather than put in a whole bunch of hooks which are probably not going +to be helpful for any purpose other than your changes. For example, +if you want to modify dbxread.c to deal with DBX debugging symbols +which are in COFF files rather than BSD a.out files, do something +along the lines of a macro GET_NEXT_SYMBOL, which could have +different definitions for COFF and a.out, rather than trying to put +the necessary changes throughout all the code in dbxread.c that +currently assumes BSD format. + +Please avoid duplicating code. For example, in GDB 3.x all the stuff +in infptrace.c was duplicated in *-dep.c, and so changing something +was very painful. Thus in GDB 4.x these have all been consolidated +into infptrace.c. infptrace.c can deal with variations between +systems the same way any system-independent file would (hooks, #if +defined, etc.), and machines which are radically different don't need +to use infptrace.c at all. The same was true of core_file_command +and exec_file_command. + +About debugging gdb with itself... + +You probably want to do a "make TAGS" after you configure your +distribution; this will put the machine dependent routines for your +local machine where they will be accessed first by a M-period . + +Also, make sure that you've compiled gdb with your local cc or taken +appropriate precautions regarding ansification of include files. See +the Makefile for more information. + +When you run gdb in this directory, it will read a ".gdbinit" file that +sets up some simple things to make debugging gdb easier. The "info" +command, when executed without a subcommand in a gdb being debugged by +gdb, will pop you back up to the top level gdb. See .gdbinit for details. + +(this is for editing this file with GNU emacs) +Local Variables: +mode: text +End: |