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