mirror of
https://github.com/darlinghq/darling-gdb.git
synced 2024-12-10 21:55:22 +00:00
260 lines
12 KiB
Plaintext
260 lines
12 KiB
Plaintext
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:
|