[external/binutils.git] / gdb / doc / gdbint.info-3

This is Info file gdbint.info, produced by Makeinfo version 1.68 from
the input file ./gdbint.texinfo.

START-INFO-DIR-ENTRY
* Gdb-Internals: (gdbint).      The GNU debugger's internals.
END-INFO-DIR-ENTRY

   This file documents the internals of the GNU debugger GDB.

   Copyright 1990-1999 Free Software Foundation, Inc.  Contributed by
Cygnus Solutions.  Written by John Gilmore.  Second Edition by Stan
Shebs.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy or distribute modified versions of this
manual under the terms of the GPL (for which purpose this text may be
regarded as a program in the language TeX).

\1f
File: gdbint.info,  Node: Porting GDB,  Next: Hints,  Prev: Coding,  Up: Top

Porting GDB
***********

   Most of the work in making GDB compile on a new machine is in
specifying the configuration of the machine.  This is done in a
dizzying variety of header files and configuration scripts, which we
hope to make more sensible soon.  Let's say your new host is called an
XYZ (e.g.  `sun4'), and its full three-part configuration name is
`ARCH-XVEND-XOS' (e.g.  `sparc-sun-sunos4').  In particular:

   In the top level directory, edit `config.sub' and add ARCH, XVEND,
and XOS to the lists of supported architectures, vendors, and operating
systems near the bottom of the file.  Also, add XYZ as an alias that
maps to `ARCH-XVEND-XOS'.  You can test your changes by running

     ./config.sub XYZ

and
     ./config.sub `ARCH-XVEND-XOS'

which should both respond with `ARCH-XVEND-XOS' and no error messages.

   You need to port BFD, if that hasn't been done already.  Porting BFD
is beyond the scope of this manual.

   To configure GDB itself, edit `gdb/configure.host' to recognize your
system and set `gdb_host' to XYZ, and (unless your desired target is
already available) also edit `gdb/configure.tgt', setting `gdb_target'
to something appropriate (for instance, XYZ).

   Finally, you'll need to specify and define GDB's host-, native-, and
target-dependent `.h' and `.c' files used for your configuration.

Configuring GDB for Release
===========================

   From the top level directory (containing `gdb', `bfd', `libiberty',
and so on):
     make -f Makefile.in gdb.tar.gz

   This will properly configure, clean, rebuild any files that are
distributed pre-built (e.g. `c-exp.tab.c' or `refcard.ps'), and will
then make a tarfile.  (If the top level directory has already been
configured, you can just do `make gdb.tar.gz' instead.)

   This procedure requires:
   * symbolic links

   * `makeinfo' (texinfo2 level)

   * TeX

   * `dvips'

   * `yacc' or `bison'

... and the usual slew of utilities (`sed', `tar', etc.).

TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
---------------------------------------------

   `gdb.texinfo' is currently marked up using the texinfo-2 macros,
which are not yet a default for anything (but we have to start using
them sometime).

   For making paper, the only thing this implies is the right
generation of `texinfo.tex' needs to be included in the distribution.

   For making info files, however, rather than duplicating the texinfo2
distribution, generate `gdb-all.texinfo' locally, and include the files
`gdb.info*' in the distribution.  Note the plural; `makeinfo' will
split the document into one overall file and five or so included files.

\1f
File: gdbint.info,  Node: Hints,  Prev: Porting GDB,  Up: Top

Hints
*****

   Check the `README' file, it often has useful information that does
not appear anywhere else in the directory.

* Menu:

* Getting Started::             Getting started working on GDB
* Debugging GDB::               Debugging GDB with itself

\1f
File: gdbint.info,  Node: Getting Started,  Up: Hints

Getting Started
===============

   GDB is a large and complicated program, and if you first starting to
work on it, it can be hard to know where to start.  Fortunately, if you
know how to go about it, there are ways to figure out what is going on.

   This manual, the GDB Internals manual, has information which applies
generally to many parts of GDB.

   Information about particular functions or data structures are
located in comments with those functions or data structures.  If you
run across a function or a global variable which does not have a
comment correctly explaining what is does, this can be thought of as a
bug in GDB; feel free to submit a bug report, with a suggested comment
if you can figure out what the comment should say.  If you find a
comment which is actually wrong, be especially sure to report that.

   Comments explaining the function of macros defined in host, target,
or native dependent files can be in several places.  Sometimes they are
repeated every place the macro is defined.  Sometimes they are where the
macro is used.  Sometimes there is a header file which supplies a
default definition of the macro, and the comment is there.  This manual
also documents all the available macros.

   Start with the header files.  Once you some idea of how GDB's
internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), you
will find it much easier to understand the code which uses and creates
those symbol tables.

   You may wish to process the information you are getting somehow, to
enhance your understanding of it.  Summarize it, translate it to another
language, add some (perhaps trivial or non-useful) feature to GDB, use
the code to predict what a test case would do and write the test case
and verify your prediction, etc.  If you are reading code and your eyes
are starting to glaze over, this is a sign you need to use a more active
approach.

   Once you have a part of GDB to start with, you can find more
specifically the part you are looking for by stepping through each
function with the `next' command.  Do not use `step' or you will
quickly get distracted; when the function you are stepping through
calls another function try only to get a big-picture understanding
(perhaps using the comment at the beginning of the function being
called) of what it does.  This way you can identify which of the
functions being called by the function you are stepping through is the
one which you are interested in.  You may need to examine the data
structures generated at each stage, with reference to the comments in
the header files explaining what the data structures are supposed to
look like.

   Of course, this same technique can be used if you are just reading
the code, rather than actually stepping through it.  The same general
principle applies--when the code you are looking at calls something
else, just try to understand generally what the code being called does,
rather than worrying about all its details.

   A good place to start when tracking down some particular area is
with a command which invokes that feature.  Suppose you want to know how
single-stepping works.  As a GDB user, you know that the `step' command
invokes single-stepping.  The command is invoked via command tables
(see `command.h'); by convention the function which actually performs
the command is formed by taking the name of the command and adding
`_command', or in the case of an `info' subcommand, `_info'.  For
example, the `step' command invokes the `step_command' function and the
`info display' command invokes `display_info'.  When this convention is
not followed, you might have to use `grep' or `M-x tags-search' in
emacs, or run GDB on itself and set a breakpoint in `execute_command'.

   If all of the above fail, it may be appropriate to ask for
information on `bug-gdb'.  But *never* post a generic question like "I
was wondering if anyone could give me some tips about understanding
GDB"--if we had some magic secret we would put it in this manual.
Suggestions for improving the manual are always welcome, of course.

\1f
File: gdbint.info,  Node: Debugging GDB,  Up: Hints

Debugging GDB with itself
=========================

   If GDB is limping on your machine, this is the preferred way to get
it fully functional.  Be warned that in some ancient Unix systems, like
Ultrix 4.2, a program can't be running in one process while it is being
debugged in another.  Rather than typing the command `./gdb ./gdb',
which works on Suns and such, you can copy `gdb' to `gdb2' and then
type `./gdb ./gdb2'.

   When you run GDB in the GDB source 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.

   If you use emacs, you will 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
`M-.'

   Also, make sure that you've either compiled GDB with your local cc,
or have run `fixincludes' if you are compiling with gcc.

Submitting Patches
==================

   Thanks for thinking of offering your changes back to the community of
GDB users.  In general we like to get well designed enhancements.
Thanks also for checking in advance about the best way to transfer the
changes.

   The GDB maintainers will only install "cleanly designed" patches.
You may not always agree on what is clean design.

   If the maintainers don't have time to put the patch in when it
arrives, or if there is any question about a patch, it goes into a
large queue with everyone else's patches and bug reports.

   The legal issue is that to incorporate substantial changes requires a
copyright assignment from you and/or your employer, granting ownership
of the changes to the Free Software Foundation.  You can get the
standard document for doing this by sending mail to
`gnu@prep.ai.mit.edu' and asking for it.  I recommend that people write
in "All programs owned by the Free Software Foundation" as "NAME OF
PROGRAM", so that changes in many programs (not just GDB, but GAS,
Emacs, GCC, etc) can be contributed with only one piece of legalese
pushed through the bureacracy and filed with the FSF.  I can't start
merging changes until this paperwork is received by the FSF (their
rules, which I follow since I maintain it for them).

   Technically, the easiest way to receive changes is to receive each
feature as a small context diff or unidiff, suitable for "patch".  Each
message sent to me should include the changes to C code and header
files for a single feature, plus ChangeLog entries for each directory
where files were modified, and diffs for any changes needed to the
manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi).  If there are a lot
of changes for a single feature, they can be split down into multiple
messages.

   In this way, if I read and like the feature, I can add it to the
sources with a single patch command, do some testing, and check it in.
If you leave out the ChangeLog, I have to write one.  If you leave out
the doc, I have to puzzle out what needs documenting.  Etc.

   The reason to send each change in a separate message is that I will
not install some of the changes.  They'll be returned to you with
questions or comments.  If I'm doing my job, my message back to you
will say what you have to fix in order to make the change acceptable.
The reason to have separate messages for separate features is so that
other changes (which I *am* willing to accept) can be installed while
one or more changes are being reworked.  If multiple features are sent
in a single message, I tend to not put in the effort to sort out the
acceptable changes from the unacceptable, so none of the features get
installed until all are acceptable.

   If this sounds painful or authoritarian, well, it is.  But I get a
lot of bug reports and a lot of patches, and most of them don't get
installed because I don't have the time to finish the job that the bug
reporter or the contributor could have done.  Patches that arrive
complete, working, and well designed, tend to get installed on the day
they arrive.  The others go into a queue and get installed if and when
I scan back over the queue - which can literally take months sometimes.
It's in both our interests to make patch installation easy - you get
your changes installed, and I make some forward progress on GDB in a
normal 12-hour day (instead of them having to wait until I have a
14-hour or 16-hour day to spend cleaning up patches before I can
install them).

   Please send patches directly to the GDB maintainers at
`gdb-patches@cygnus.com'.

Obsolete Conditionals
=====================

   Fragments of old code in GDB sometimes reference or set the following
configuration macros.  They should not be used by new code, and old uses
should be removed as those parts of the debugger are otherwise touched.

`STACK_END_ADDR'
     This macro used to define where the end of the stack appeared, for
     use in interpreting core file formats that don't record this
     address in the core file itself.  This information is now
     configured in BFD, and GDB gets the info portably from there.  The
     values in GDB's configuration files should be moved into BFD
     configuration files (if needed there), and deleted from all of
     GDB's config files.

     Any `FOO-xdep.c' file that references STACK_END_ADDR is so old
     that it has never been converted to use BFD.  Now that's old!

`PYRAMID_CONTROL_FRAME_DEBUGGING'
     pyr-xdep.c

`PYRAMID_CORE'
     pyr-xdep.c

`PYRAMID_PTRACE'
     pyr-xdep.c

`REG_STACK_SEGMENT'
     exec.c