From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 29823 invoked by alias); 9 Oct 2003 23:28:35 -0000 Mailing-List: contact insight-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: insight-owner@sources.redhat.com Received: (qmail 29816 invoked from network); 9 Oct 2003 23:28:34 -0000 Received: from unknown (HELO mx1.redhat.com) (66.187.233.31) by sources.redhat.com with SMTP; 9 Oct 2003 23:28:34 -0000 Received: from int-mx1.corp.redhat.com (int-mx1.corp.redhat.com [172.16.52.254]) by mx1.redhat.com (8.11.6/8.11.6) with ESMTP id h99NSXM28010 for ; Thu, 9 Oct 2003 19:28:33 -0400 Received: from pobox.corp.redhat.com (pobox.corp.redhat.com [172.16.52.156]) by int-mx1.corp.redhat.com (8.11.6/8.11.6) with ESMTP id h99NSXc20041; Thu, 9 Oct 2003 19:28:33 -0400 Received: from [150.1.200.14] (vpn50-36.rdu.redhat.com [172.16.50.36]) by pobox.corp.redhat.com (8.12.8/8.12.8) with ESMTP id h99NSVdT015390; Thu, 9 Oct 2003 19:28:32 -0400 Subject: Re: hacking insight From: Keith Seitz To: Deepti Mokkapati Cc: "insight@sources.redhat.com" In-Reply-To: <200309292015.54166.mokkapati@ittc.ku.edu> References: <200309292015.54166.mokkapati@ittc.ku.edu> Content-Type: text/plain Organization: Message-Id: <1065742291.1590.144.camel@lindt.uglyboxes.com> Mime-Version: 1.0 Date: Thu, 09 Oct 2003 23:28:00 -0000 Content-Transfer-Encoding: 7bit X-SW-Source: 2003-q4/txt/msg00035.txt.bz2 On Mon, 2003-09-29 at 18:15, Deepti Mokkapati wrote: > I want to hack insight for adding some Tcl/Tk interfaces as my class project. > Could someone tell me where can I get the outline of insight code that will > help me in understanding Insight better? Unfortunately, there is no real outline of the code. I can provide some information, though. (I seem to recall writing this all once before. Maybe this time I'll save it all and put it somewhere online.) Insight is actually a pretty simple application. Insight works quite well. Gdb (the GNU Debugger), on the other hand, is, well, ancient, and pretty good as far as old debuggers go. Nonetheless, it's all we have, and today's faster computers and current (gdb) development efforts make it tolerable to work with (for an ancient debugger). [Of course, IMO Insight is the only thing that makes gdb useable! :-)] First let me start by saying that as far as Insight is concerned, I believe it is dead. I have currently zero motivation to work on it, much less answer questions and fix bugs. Martin Hunt and I are the only two really "active" (our should I say "infrequently active") contributors, and, even though our email addresses say "@redhat.com" and redhat OCCASIONALLY pays us to work on insight, it more or less has nothing to do with it. Demoralizing? You bet. What makes it worse is that I'm certain there are tons of corporate leaches out there who use and distribute Insight, come here for bug fixes, and then do nothing to contribute back anything. Zippo. [Okay, that's not entirely true, but corporate contributors are essentially zero. I do apologize if I've ommitted anyone specifically, but I'm getting old, this email is long, and I'm caring less with every passing day.] It seems with Insight, it's all take and no give. Demoralizing? Aboslutely. Let me reiterate one thing again: No one is paid to work on Insight. Not Martin, not me. No one. (Okay, maybe someone is, but I certainly don't know anything about it.) Now I understand that people will say they don't contribute because they don't like to use tcl/tk, blah, blah. Too bad. That's what Insight was originally written in, and it was written that way for a reason: the company that originally developed it (Cygnus Solutions, now owned by Red Hat), needed it to work on both unix (SunOS, Solaris, HP-UX, AIX, and others) _and_ Windows. At the time, Tk was the only suitable answer. [Things look a little different now, almost five years later.] I also understand that there is some confusion about who owns Insight. It has always been my expectation that Insight is like gdb, under the GPL, including the Tcl code. There was some goofiness over at the FSF and the whole "Tcl is bad" thing years ago. Perhaps the attitude has changed. I'm going to see if I can clear all this mess up and establish proper procedures for code contributions. Although I've toyed with the idea of starting Insight over in C++ using some modern cross-platform toolkit, I cannot convince myself that things would end up any differently than they are now. Anyway, enough ranting, it's time to get back to your original question. One important thing to note about Insight: unlike _all_ other GUIs on top of gdb out there, Insight IS gdb. It does not run as a separate executable; it is the same executable. Crashes in gdb crash Insight (and vice-versa). If you look at the layout of the insight sources, they're basically arranged the way any tcl application is. gdbtk/generic contain generic C source files that act predominantly as glue code between gdb and the Tk UI (gdb was never written to interface to a graphical user interface, so getting useful information out of it is like hacking your teeth out with a pencil). The main UI code lies in the gdbtk/library folder. Of the UI code, one file (in particular) is used as some glue between the C code (in gdbtk/generic) and the UI code. This file is interface.tcl. It contains most of the tcl hook functions that are called from the C code, although I did, at one time, start migrating AWAY from this outdated method of doing things. Unfortunately, I think we're stuck with a lot of it now. A hook is a function that is called (by the core gdb code when the hook is "defined")) that tells the UI that something has happened. For example, when a user types "file foo" at the console window, gdb goes off and loads the symbol and executable file "foo". So how does the UI find out that this has happeneded (so that it can update the Source window and the like)? Well, deep in the bowels, gdb does something like: if (file_command_hook) file_command_hook (filename); (This isn't exactly what it does, but it's darn close.) So the "hook" that tells us this has happened is called by gdb. We simply define a function with the hook's signature and define it somewhere; something like: void gdbtk_file_command_hook (const char* filename); /* ... */ file_command_hook = gdbtk_file_command_hook; So hooks are really a degenerate type of event notification -- they're not asynchronus at all like real events. All of the hooks used by Insight (which used to be called "gdbtk") are defined in gdbtk/generic/gdbtk-hooks.c. [For a while, gdb was migrating to "events", in the hopes of making them truly asynchronus entities, and the corresponding handlers for all that is also in gdbtk-events.c. Think of the two as basically the same.] So the main communications channel between gdb and insight are these hooks/events. When something happens to cause an event, the hook is called (or the event handler is invoked) and insight usually passes the information directly through to the Tcl interpreter (it may manipulate it a little first). The code that is called is almost always in interface.tcl (although it could be in ehandler.itb (see GDBEventHandler::dispatch). So, that's basically all the C code does -- help the Tcl UI procedures get information to/from gdb. Okay, there is one more thing. Windows in Insight are really event handlers. Since events can either happen as "events" or "hooks", there are two ways to deal with them. First, the "old" way: hooks. Windows register and unregister for any hooks in which they are interested. So if your interested in hook "foo_hook", your window code would call (usually in its constructor or by something from its constructor) "add_hook foo_hook [code $this foo_hook_handler]". This registers the method call "$this foo_hook_handler" as a callback whenever "foo_hook" is invoked. Likewise, it is unregistered by calling "remove_hook". For an explicit example, look at SrcTextWin::constructor and the hooks added near the end of this function. Unregistering occurs in destructor (amongst other places). Second, the "new" way: events. Windows responding to gdb events inherit from GDBEventHandler (or more commonly from GDBWin which inherits from GDBEventHandler). GDBEventHandler has default, do-nothing implementations of all the events that can be called. If you want to respond to a particular event, simply overload the method of the event you're interested in. For example, if I'm interested in breakpoint events, I can overload the method "breakpoint" in GDBEventHandler. ehandler.ith and gdbevent.ith define all the events. (One of the things that we could do is get rid of all the add_hook/remove_hook stuff and implement them as events in GDBEventHandler, but alas, there was no real powerful motivation to do this.) I guess I should mention some of the important hooks/events. Without doubt, the most important hooks/events are gdbtk_busy_hook, gdbtk_idle_hook, and gdbtk_update_hook (which I believe have been replaced with the events BusyEvent, UpdateEvent, and IdleEvent). These are the most vital, yet most misunderstood events/hooks in insight. They are well documented in interface.tcl (look for gdbtk_update, gdbtk_idle, and gdbtk_busy) and gdbevent.ith. Please read those descriptions carefully. [For the impatient: they prevent the user from asking gdb to do too many things at once. We must be sure that gdb does one thing, and finishes it before asking it to do another.] So, enough about backend-frontend communications, let's look at how the actual UI code works. Most windows in Insight inherit from GDBWin, which, amongst other things, gives it access to the event handlers (but not hooks, which for which windows must independently register). Right now, gdbwin does next to nothing. It was a placeholder to allow windows to be attached to the source window and the like, but that work was never completed. [This was needed for the case that gdb became truly "multi-arch" capable, i.e, it could debug multiple processors at one time or even multiple processors of different architectures.] [Small aside: We use Itcl. Think of Itcl turns tcl from a purely procedural language to more object oriented, similar to C and C++. With Itcl, one can have "header" files with class definitions and "implementation" files where the guts of everything is implemented. In Itcl, a class's definition may NOT change once it has been defined. However, you may change any class method or procedure AT RUNTIME. So we keep almost all the implmentation details in the "*.itb" files, which we can be reloaded into a running version of insight to debug.] Well, so now most of the UI code is arranged inside gdbtkk/library. Most of it is pretty obvious. srcwin.it? is the source window code. srctextwin.it? is the text pane used by the source window. debugwin.it? is the debug window, and on and on. That's all there really is, but I guess I should mention the plugin architecture: there is one. Read the documentation on it in gdbtk/plugins/HOW-TO. Of course, if there are specific questions, send to the list, and maybe someone will answer them. Maybe even me. I'll go skulk back into the hole from which I came now. Good luck. Keith