Writing your own plugins for the Flex Builder debugger, part 1: where to start

Is there a feature missing from the Flex Builder debugger that you really wish we had put in?

No? Right, move along then.

Oh, what’s that? Yes, there is such a feature? Well then, now is your chance for fame and glory. (Notice I didn’t say fortune. That part probably takes more work than just writing a plugin.)

There is bad news and good news. The bad news is, in this release we will not be publishing the Flex-specific debugger APIs that live inside Flex Builder. We just haven’t had time to clean them up and test them to the degree that we would be comfortable releasing them as documented, supported APIs.

But, the good news is, our lack of Flex-specific APIs is not as big a problem as it might sound like at first, because Eclipse itself has a very clean, well-documented set of APIs for accessing generic debugger-related functionality (variables, breakpoints, callstacks, etc.). And it turns out that the vast majority of stuff that you can think of putting into a Flex Builder debugger plugin is actually generic debugger stuff, not Flex-specific.

For example, using the Eclipse APIs, here are a few things you can easily do within your own Flex Builder plugin:

• given a string, evaluate it as an expression
• change the value of a variable
• set a breakpoint
• determine the current callstack
• programmatically invoke step-into, step-over, resume, terminate, etc.

Okay, so where to start? In future posts I will give some actual code samples, but for now, here are a few key starting points inside Eclipse:

• Much of the key stuff is in the Java package org.eclipse.debug.core.model – this includes IVariable, IValue, IThread, IStackFrame, IDebugTarget (a program being debugged), IProcess (a program that was launched with either Debug or Run), IBreakpoint, ILineBreakpoint, IExpression, IWatchExpression.

• Also, a common starting point for getting anything done is a call to org.eclipse.debug.core.DebugPlugin.getDefault(). From there, you can get to the IBreakpointManager, ILaunchManager (again, a “launch” is anything that you launched with either Debug or Run), and IExpressionManager; and add a debug event listener so your code is notified when something interesting happens.

• Finally, class org.eclipse.debug.ui.DebugUITools has some useful helper functions. In particular, DebugUITools.getDebugContext() is more important than its bland name implies. The “debug context” is whatever is selected in the Debug view, such as a particular stack frame. This ends up affecting lots of things, like which variables are shown in the Variables view, and how expressions are evaluated: Expressions are evaluated in the context of the current stack frame.

The online documentation for all the Eclipse debugger classes is here (scroll down to the org.eclipse.debug.* packages).

Finally, I want to warn you that learning how to write Eclipse plugins is a very time-consuming undertaking. Eclipse is extremely modular – there are design patterns everywhere you turn. And that’s a good thing, because it gives you tremendous power to plug into it at any level (if this weren’t the case, we wouldn’t have been able to create something like Flex Builder on top of it).

But the downside of this modularity is that it’s really hard to just plunge in and start creating useful code, because it can be very hard to figure out how to get from point A to point B. (An example: Early on, I tried to figure out the code path from “user double-clicks in the margin of a document” to “blue circle shows up indicating a breakpoint has been created.” Whoo boy.) It took me about a month of full-time development before the lightbulb in my head finally lit up and I “got” how everything fits together; I then began to find it much quicker to write code.