diff options
Diffstat (limited to 'gdb/doc/gdbint.info-3')
| -rw-r--r-- | gdb/doc/gdbint.info-3 | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/gdb/doc/gdbint.info-3 b/gdb/doc/gdbint.info-3 new file mode 100644 index 00000000000..aa1fd565f9d --- /dev/null +++ b/gdb/doc/gdbint.info-3 @@ -0,0 +1,316 @@ +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). + + +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. + + +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 + + +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. + + +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 + + |