diff options
Diffstat (limited to 'gdb/gdbtk/README')
| -rw-r--r-- | gdb/gdbtk/README | 283 |
1 files changed, 0 insertions, 283 deletions
diff --git a/gdb/gdbtk/README b/gdb/gdbtk/README deleted file mode 100644 index d8756430b9e..00000000000 --- a/gdb/gdbtk/README +++ /dev/null @@ -1,283 +0,0 @@ - README - Written by Stu Grossman - Updated 9/26/95 by Fred Fish for gdb 4.15 release - Updated 4/18/97 by Martin Hunt - Updated 8/15/02 by Keith Seitz - -This file describes how to build, install, use and hack on Insight (formerly -GDBtk), a TK-based GUI for GDB, the GNU debugger. - -Introduction -============ - -Insight is a version of GDB that uses Tcl/Tk to implement a graphical -user inter-face. It is a fully integrated GUI, not a separate -front-end program. The interface consists of several separate -windows, which use standard elements like buttons, scrollbars, entry -boxes and such to create a fairly easy to use interface. Each window -has a distinct content and purpose, and can be enabled or disabled -individually. The windows contain things like the current source -file, a disassembly of the current function, text commands (for things -that aren't accessible via a button), and so forth. - -Building and Installing -======================= - -Building Insight is very straightforward. It is configured/built by -default when you checkout or download Insight. Right now, Insight MUST -be built using the versions of Tcl, Tk, Itcl, and Tix that come with -the sources. We're working to fix that, but it is going to take a lot -of time. (Want to help?) - -On Unix machines, you will also need to have X11 (R4/R5/R6) installed -(this is a prerequisite to installing Tk). - -Insight inherits much of GDB's configuration options (like where it is -to be installed). See the GDB README file for more details on configure -options and such for GDB. - -It is recommended that Insight, like GDB, be built outside of the source -directory in order to preserve the integrity of the source directory. This -is very useful, for example, when building GDB/Insight for multiple hosts -or targets. - -For example: - - host> ls - src/ - host> mkdir insight; cd insight - host> ../src/configure - host> make - host> make install - -Environment Variables -===================== - -Insight and all of its support infrastructure read various environment variables -for optional startup information. All of these environment variables are -optional: Insight and its packages know how to find their files in both the -install and the source trees. - - Name Description - ---- ----------- - TCL_LIBRARY The location of the Tcl library files - TK_LIBRARY The location of the Tk library files - TIX_LIBRARY The location of the Tix library files - REDHAT_GUI_LIBRARY The location of the libgui library files - GDBTK_LIBRARY The location of the Insight library files - INSIGHT_PLUGINS A colon-separated list of directories - to search for plugins (see gdb/gdbtk/plugins/HOW-TO) - GDBTK_DEBUG Controls runtime loading of the Debug Window. - (This is the most useful debug option.) - GDBTK_TRACE Controls runtime tracing of the tcl code - GDBTK_DEBUGFILE Filename to send debug output - GDBTK_TEST_RUNNING Testsuite variable. See gdb/testsuite/gdb.gdbtk/README - for more information. - -All of the environment variables for controlling Insight are well documented -in gdb/gdbtk/library/main.tcl. Search for "env" to find them all. - -Using Insight -============= - -Just run it like you would a normal GDB (in fact, it's actually called `gdb'). -If everything goes well, you should have several windows pop up. To get going, -hit the Run button, and go exploring. - -If you want to use GDB in command line mode, just use the -nw option. Or, you -can undefine the DISPLAY environment variable. - -Insight comes with all your standard debugger windows, including: - - o Console Window - o Source Window - o Register Window - o Memory Window - o Locals Window - o Watch Window - o Stack Window - o Thread/Process Window - o Function Browser Window - o Debug Window (for developers) - -Insight also has an extensive (if outdated) online help system which describes -all the windows and explains how to use them. Users are urged to browse this -help system for information on using Insight. - -Hacking Insight -=============== - -The GUI is primarily implemented by Tcl/Tk code which lives in gdb/gdbtk/library - and bunch of C files in gdb/gdbtk/generic. The Tcl/Tk code determines the look -and feel, the layout, and the functions associated with all of the interface -elements. The C code is mostly just glue between GDB internals and Tcl-land. -In essence, all of the policy is implemented in Tcl/Tk, and is easily changed -without recompiling. - -To make more serious changes to the interface, such as adding a new window or -changing the framework, you will have to hack the tcl code (and probably the C -code as well). The tcl library install directory is $(libdir) (probably -/usr/local/lib/insight1.0). But, you will probably want to hack on your own -private copy before putting it up for the rest of the users. To find the GDB tcl -code, GDB first checks for the environment variable GDBTK_LIBRARY. GDB will check -this directory for the file "main.tcl". If GDBTK_LIBRARY is not set, GDB will -look for main.tcl in the install directory, and finally it will try to find -the tcl directory in the sources. - -A word about the different files in Insight is in order. Insight is a hybrid of -C code and "Tcl" code (actuall Incr Tcl code). We use the following conventions -for naming our tcl files (most of the time!). Any file with a ".tcl" extension -is simply vanilla tcl code. Any file ending with ".itcl" is an Itcl file, -class definition and implementation all in one. So far so good. Now comes the -toughy: Files ending in ".ith" are Itcl class definition files, and they all -must have a corresponding implementation file, ending in ".itb". Why do we do -this? Simple. With Itcl, one can reread class implementations at runtime, but -one cannot change the class definition. So all those ".itcl" files can only -be reread be restarting Insight. The same is not true, though, of the ".itb" -files. Those files can be changed and immediately reread and used in Insight -without having to restart (as long as the class definition doesn't change). This -is a nifty Itcl feature which is fully exploited by the Debug Window, which -has a "ReSource" menu on it to reread the Tcl files. (To get to the Debug Window, -hit Ctrl-Alt-F11 in the Source Window or type "tk ManagedWin::open DebugWin" in -the Console Window.) - -Internally, Insight is basically GDB, linked with Tcl/Tk, some Tcl/Tk extensions, -and some glue code that interfaces GDB internals to Tcl-land. This means that -Insight operates as a single program, not a front-end to GDB. All GDB commands, -and a great deal of the target program state are accessible to the Tcl programmer. -In addition, there are many callbacks from GDB to notify Tcl-land of important -events. Many of these are accomplished via "hooks" in GDB, and others are -accomplished using event notifications. GDB is slowly deprecating the use of -"hooks" in favor of its new event mechanism. - -All of the below commands have lots of nice comments before them explaining what -they all do, how they are to be used, etc. The source code is the definitive -authority (other than a maintainer) for the definition/usage of a command in -Insight. Hackers are urged to read through the source code for any commands -which may need explaining. - -New Tcl Commands: - -Here is a brief, if incomplete, summary of the Tcl commands that are created -by Insight. These are installed into the Tcl interpreter in the C files. - - Name Description - ---- ----------- - gdb_cmd Sends a text command to gdb. Returns the result. - DEPRECATED: Do not use any more. - gdb_loc Returns a list of useful tidbits about the specified - GDB linespec - gdb_sourcelines Returns a list of executable lines for a source file - gdb_listfiles Returns a list of all of the source files - gdb_stop Stops the target process (or at least tries to) - gdb_reginfo Returns information about registers (names, numbers, - values, size, etc.) - gdb_disassemble Returns the text of a disassembly of the entire - function. No longer used. - gdb_load_disassembly Loads the disassembly of a location into a - source window's textbox - gdb_eval Returns the value of a given expression - gdb_get_breakpoint_list Returns a list of all breakpoints - gdb_get_breakpoint_info Returns a list of info about a breakpoint - -Tcl procedures that are hooked into GDB: - -This is a list, albeit incomplete, of the "hook" functions that are installed -into GDB. The actual "hooks" are installed/initialized in -gdb/gdbtk/generic/gdbtk-hooks.c (and maybe one or two in gdbtk.c). The list -below is the Tcl side of the hook. - - Name Description - ---- ----------- - gdb_tcl_fputs Sends output into Tcl for the command window - gdb_tcl_query Pops up a query window - gdbtk_tcl_breakpoint Notifies Tcl of changes to a breakpoint - gdbtk_tcl_idle Notifies Tcl that debugged process is now idle - gdbtk_tcl_busy Notifies Tcl that debugged process is now running - -Events: - -Starting with GDB 5.0, GDB has had an event loop. Although largely unused right -now, with it came some useful "baggage", especially event notifications, even -though they, too, were largely incomplete. The list of events continues to grow, -and Insight and GDB often "share" overlapping events, but the list below is -complete (since there are only a few defined events). The source for these -events can be found in gdb/gdbtk/library/gdbevents.it[hb]. - - Name Description - ---- ----------- - BreakpointEvent A breakpoint has been created/modified/deleted - TracepointEvent A tracepoint has been created/modified/deleted - SetVariableEvent User has issued a "set" command in Console - BusyEvent The debugger is "busy" - IdleEvent The debugger is "idle" - UpdateEvent The state of the target has changed (or the - GDB's view of the target has changed) - ArchChangedEvent The architecture of the system has changed - (this can happen when GDB defaults to using - some basic CPU and detects that a more elaborate - CPU is actually being used, e.g., SH5) - -GDB Commands: - -Insight installs a few GDB commands, which are available with the Console Window. - - Name Description - ---- ----------- - tk Executes the arguments in the Insight Tcl - interpreter - view Displays the given linespec in the Source Window - -Problems -======== - -During building, you may run into problems with finding Tcl, Tk or X11. Look -in gdb/Makefile, and fix TCL_CFLAGS, TCL, TK_CFLAGS, TK, and ENABLE_CLIBS as -appropriate. - -If you one of the following messages when you run gdb: - - Tcl_Init failed: can't find init.tcl; perhaps you need to - install Tcl or set your TCL_LIBRARY environment variable? -or - Tk_Init failed: can't find tk.tcl; perhaps you need to - install Tk or set your TK_LIBRARY environment variable? - -then you haven't installed Tcl or TK properly. Fix the appropriate environment -variable to point at the {tcl tk}/library directory, and restart gdb. - -Known Bugs -========== - -generic problems - - o Using the GDB commands "up"/"down"/"frame" in Console Window - can cause GDB and Insight to get out of sync. If this happens, - simply use the Stack Window or the frame navigation buttons on - the Source Window's toolbar to resync the two. - - o Not really a problem, but it might be nice to have a frame/stack - window that displays the last N words on the stack, along with - indications about which function owns a particular frame, how the - frame pointers are chained, and possibly the names of variables - alongside their frame slots. - -host- or target-specific problems - - o Windows is hosed. Tk8.3 in sources.redhat.com is not stable - on windows. Wanna help? - -Where to find help -================== - -The first place to turn for help is the online help system. It may be old, but -it is still largely correct: it explains what everything does. If that fails, -search the mailing list archives for other users who may have had similar problems -or questions. The archives are online at - -http://sources.redhat.com/insight/mailinglist.htm . - -If all else fails, send a note to the mailing list, insight@sources.redhat.com, -where users and maintainers lurk. This is a very low traffic list, so don't -be afraid to join the list. Instructions for joining are on our homepage, -http://sources.redhat.com/insight . |