Getting Started Working on GDB
******************************

   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 (see Submitting Patches.).  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 has a list of macros
     (see Host Conditionals., see Target Conditionals., 
see Native Conditionals., and see Obsolete Conditionals.) with
     some documentation.

   * 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.

   Good luck!