Re: hacking insight

[Keith Seitz <keiths at redhat dot com>]

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