But a recent email exchange with Ilan Avigdor and Yoav Moran contained some information that I think is worth sharing here. They are "creating a tool for visualizing code execution for AS3," and had some questions about the internal workings of fdb, the free open-source command-line debugger that comes with the Flex SDK. I wrote back to them with some details, and I thought I would repost my notes here. (This post is pretty rough, because I'm just taking the email conversation, doing a little light editing, and then posting it.)

The part they wanted to know about is how stepping (step into, step over, etc.) is handled by fdb.

A command-line debugger for Flex? And it's free? And it's open-source?

But first: Yes, it's true, there is a free, open-source command-line debugger for Flex. I get the feeling a lot of people are unaware of that. Just as the command-line compiler, mxmlc, is free and open-source, the same is true of the debugger, fdb. It, like all the other Flex tools, is written in Java.

fdb.jar actually serves two purposes:

1. It is a Java library with an API that is callable from any Java program you write. E.g. if you wanted to write your own WYSIWYG Flex debugger, you could just put fdb.jar inside your app, and then call its Java API -- stepInto() and so on.
2. In addition, in the same jar is the command-line debugger. The command-line debugger portion of fdb.jar makes calls to the API portion of fdb.jar.

The Java library portion of fdb.jar is actually opening a socket and connecting to the Flash Player which is running in a separate process (e.g. in your web browser). Yes, there is a wire protocol, so you don't have to use fdb.jar -- you could write directly to the wire protocol -- but that is harder, especially since the wire protocol isn't publicly documented.

Reading the source

Top-level location: http://opensource.adobe.com -- this is the entry point for all of Adobe's open-source code.

Flex SDK location: http://opensource.adobe.com/svn/opensource/flex/sdk/trunk -- this is a Subversion repo, so for example you can download all the sources with this command, to put them in a subdir called "flex" under the current directory:

svn co http://opensource.adobe.com/svn/opensource/flex/sdk/trunk/ flex

(That will pull down a lot more than just fdb.) fdb is in the modules/debugger subdirectory of that. Under modules/debugger, src/java/flash contains the API portion, and src/java/flex contains the code for the command-line fdb program. The class flex.tools.debugger.cli.DebugCLI is the entry class of the whole fdb program.

How stepping works

First, as in many debuggers, there are three kinds of stepping:

• Step into: Single-step, and if we step into a function call, then halt at the first line of that function call.
• Step over: Step over the current line until we reach the next line of the current function. Do not halt inside nested functions.
• Step out: Step until we exit the current function.

The function runningLoop() is one of the more important functions related to stepping: It is in charge of repeatedly telling the Flash player to resume until it decides it is time to stop.

Here is how stepping works:

When fdb sends any of the stepping-related commands to the flash player -- step in, step over, or step out -- the player says, "Okay then, how deep is the callstack at the present time?" and then uses either that number (for step over), or that number plus one (for step in), or that number minus one (for step out) as the target callstack depth for when the step command will be finished. And Flash's opcode instruction set includes a "debugline" opcode that means "I am at the beginning of a line of source code" -- so the Flash player will only do this check of the callstack depth each time it reaches a "debugline" opcode.

E.g. suppose the callstack has three functions on it, and you call "step over". Then the player records the number 3, which means, "the next time I reach a debugline opcode and the callstack depth is 3 or less, halt." At that point, the code might call into another function (so the callstack depth will be 4), and that function might call into a whole bunch of others (so the callstack depth will keep getting deeper); but eventually it will pop back to the next line of the original function, and the callstack depth will be 3, and it will halt.

Next scenario: Instead of step over, you call "step in". The player then records a target callstack depth of 4 -- again, this means, "the next time I reach a debugline opcode and the callstack depth is 4 or less, halt." Which in essence means that the very next debugline opcode will cause it to halt, no matter whether the current line of code called another function (in which case the callstack depth will be 4, because you'll be in the new function), or just did something like an assignment to a variable (in which case it will be 3, because you'll be on the next line of the same function), or did a "return" (in which case it will be 2, because you will have returned to the caller). But it'll halt.

Last scenario: You call "step out". Then the player records a target callstack depth of 2. It will keep stepping until the current function eventually returns.

Okay, so, your app: You always call "step in". Now suppose the current callstack has only one function on it (so it has a callstack depth of 1); and you call "step in," so the player records this as "halt the next time we reach a debugline opcode and the callstack depth is 2 or less"; but then the current function does a "return". We are no longer in ActionScript code -- the Flash player's native code is back in charge. It can do whatever it wants, but the key point is, eventually, the next time it calls any ActionScript code for any reason, and a "debugline" opcode is encountered, the ActionScript part of the Flash player will notice that it is supposed to stop. It doesn't matter that the code that is now executing is totally unrelated to the code that was executing before (e.g. the beginning of a new frame or whatever) -- it will stop.

That's why I am so excited with all the wonderful tools that are becoming more and more prevalent, that allow me to work in the medium in which I am so comfortable -- good old plain text -- and yet to output to very rich formats.

For example:

• I am writing this blog post in Markdown using the Markdown plugin for WordPress. Awesome! i love it. I no longer have to fight with the WordPress rich text editor.

• I recently needed to create some UML Sequence diagrams to demonstrate flow through the different components of a program I was writing. I'm on a Mac, so I can't use Visio. I spent a long time looking at a number of different options, like OmniGraffle, Gliffy, and so on. Finally, I found websequencediagrams.com, which is awesome. It lets me write a plain-text description of the interactions between the components -- for example:

  iPhone->Server: send request
  Server-->iPhone: xml
  

  ... and it will instantly create the UML sequence diagram for me:

  

  Once you have this capability, the possibilities are endless. For example, websequencediagrams.com makes it easy to write your own scripts in Python, Ruby, Java, or whatever, and create the sequence diagrams. So the point is, I can create the text representation locally on my own computer and check it into source control, and then recreate the resulting diagram whenever I want.

• yUML is similar, but for other kinds of UML diagrams such as class diagrams. Again, you just write it down in plain text, and it lays out and creates a pretty diagram. For example, with this input:

  [Customer]1-0..*[Address]
  

  ... you get this image:

  

• In case it wasn't obvious, both of the above services make it easy to just put an <img> tag in your own web page and point to their server, and your diagram will show up.

• And then there are things like PanDoc, which makes it possible to write an entire book in Markdown. Today I came across The Little MongoDB Book via Hacker News. So the guy writes the book in Markdown, and then runs PanDoc which creates a very nice-looking PDF out of the whole thing. And of course he stores the original Markdown in GitHub.

This is the way things are supposed to be. It feels so right.

Since I'm a Google fan and an Apple fan, and feel that both companies are really good at making things easy, and since my wife and I are both on Macs now, I thought I'd see how good a job those companies do.

For Google, searched for info on how to do mailing labels in Google Docs. They claim to support labels, but their "solution" is hilariously bad: Start with a document template (people upload tons of them), and then manually change each label. Ha!

Apple's solution is hard to find (I found it by googling), but once you do find it, it's awesome. Export your list to a CSV file, then import the data into the Address Book app, and then say File > Print. One of the printing choices is Labels; and you can specify which Avery label type you want, and you're done!

And they did a beautiful job of handling a few issues I was worried about:

• I don't normally use Address Book, so it was okay with me if it clobbered existing data that I had in there, but I was wondering if this would work for people who do actively use Address Book. It works fine. First I created a new "Group" called "Christmas Labels 2010". Then I imported into that group. If there are any imported entries that appear to be duplicates of existing entries, it asks me what I want to do (merge, keep both, etc.). I just told it to keep both. Then, after printing my labels, I deleted all the entries I had imported, and then deleted the group.
• My Excel spreadsheet is formatted in a way that isn't really compatible with the Address Book fields. Address Book has separate fields for first name, last name, address, city, state, zip. My spreadsheet just had three columns: "Last Name" (which was actually the full name), "Street", and "City, State, Zip". When I imported, Address Book did a good job of guessing which field each one should go into, but of course it might import one entry with the last name "The Smith Family" and no first name, and the city "San Francisco, CA 94134", and no state or zip code. Okay, that's incorrect. But it wasn't a problem. When I said to print, the labels looked just fine. (And no, there was not an extra space before "The Smith Family" on the labels, even though it is trying to print "<firstname> <lastname>".)
• Although by default it didn't guess the correct encoding of the CSV file, I was able to manually specify UTF-8, for the handful of entries that had special characters.
• A few entries had text that was too long to fit in the default font. Address Book handles that gracefully -- it just printed those ones in a smaller font.

So it's a knockout punch, Apple wins.

This drives keyboard-heavy users (like me) crazy. However, it turns out that there is a way to dismiss this dialog from the key:

Type Shift+Return instead of Return.

There is, in fact, a good reason why this dialog has a multi-line edit box. As explained in this Eclipse bug, some languages (including Java) allow you to enter more than just a simple expression into this box. And since the dialog comes from Eclipse's code rather than from Flex Builder's, we can't just change it to have a single line.

Since this is such a common point of frustration for Flex Builder users, in the above-linked bug I have asked that they find some way to make this easier for people to deal with, e.g. by perhaps having a short message in the dialog mentioning Shift+Return. But in any case, you now know the secret handshake -- enjoy!

The code:

package {
    import flash.display.* 
    import flash.text.*

    public class AprilFools extends Sprite {
        エイプリルフール var Number = 4..toString()

        use namespace エイプリルフール

        function AprilFools()
        {
            get = set
            set = get

            with (createTextField())
                text = new Date(Number).toDateString()
        }

        function get get() { return Number + <>< {Number}
            b={"/"+Number.split(/\//)[0]*502.25}/></>..@b }
        function set get(set) { Number = set+'/'+set/4 }

        function get set() { return Number }
        function set set(get) { Number = get }

        // nothing fun here
        function createTextField():TextField
        {
            stage.scaleMode = StageScaleMode.NO_SCALE;
            stage.align = StageAlign.TOP_LEFT;
            var textField:TextField = new TextField();
            textField.width = 1000;
            addChild(textField);
            return textField;
        }
    }
}

namespace エイプリルフール

The program's weak spot is creativity in terms of what it actually does -- just some static text output. Pretty pathetic really. All my effort went into the ActionScript. Click here to see the result. It's probably not worth the effort to try to figure out what it does before running it; that's not really the fun part. The fun part is trying to figure out why the heck the thing compiles at all; what the individual lines of code actually mean; and what sick features of the language I am taking advantage of. Tell me what you find.

Even if you aren't the kind of person who uses the scroll wheel on your mouse or two-finger scroll on your trackpad, please do it.

If you do, you will make some of your users very very happy.

mxmlc and compc have a -dump-config option to dump all settings to a file. Later, the settings in that file can be read back in with -load-config.

So, do this:

• In Flex Builder, do Project Properties
• Click the "Flex Compiler" tab
• In the "Additional compiler arguments" box, add "-dump-config full-path-to-output-file". For example, on Windows, "-dump-config C:\myconfig.xml"; on Mac, "-dump-config /Users/myname/myconfig.xml". (If you use a relative path, the file will be put in some odd hard-to-find place.)
• Click OK.  If Build Automatically is on, just clicking OK will cause the file to be built; if it is off, do a build now.
• Now that the settings have been dumped, go back to your project settings and remove the -dump-config option.
• Tweak the settings file as necessary (one thing you will almost certainly want to do is change <debug>true</debug> to <debug>false</debug> if your nightly build is supposed to do a release build), and use it in your nightly build script.

Please be aware that this only captures compiler settings; it doesn't capture all the other little things that Flex Builder does for you, like compiling Flex library projects that your project depends on, copying non-embedded assets to the output directory, optimizing modules for the application, extracting RSLs, copying the HTML template, and so on.

More info here. Please read that, it has additional info you will probably need.

I typed Donner, as in Donner Pass.  The iPhone "corrected" that to Dinner.

Um, yeah, that's appropriate.

(I'm also sick of the iPhone changing its to it's.  Its spell checker doesn't know what it's doing!)

Any other funny ones?

A variation of that happened to me just today.  I decided to try Yahoo Chess (and I'm proud to say I won my game).  You enter a room, e.g. the beginner room, and then there is a list of tables; you click to join a particular table.  But every few seconds, the list of tables keeps refreshing, so the button you were about to click could have suddenly disappeared -- or worse, turned into a button for a different table you didn't intend to join.

What's interesting to me (I don't know why, maybe because I'm a geek) is that this is a real-life version (if using the computer is considered real life) of the sort of race condition horribleness we all run into when we write multithreaded code. Thread 1 tries to increment a variable, but oops, thread 2 sneaks in there and changes it!  Urgh.

Does this ever come up in real real life (as opposed to real life while using a computer)?  Yes, of course -- one good example is the awkward little dance we all do once in a while when trying to walk past someone else who is coming the other way. Both step to the right, oops, both step to the left, oops!

In the case of computer UI, I can think of two ways to alleviate this problem (I am not claiming any incredible insight here, I think these are pretty obvious):

1. Animation can help. E.g. in the example of the Yahoo Chess list of tables, when the list redraws, rather than having it redraw instantly as it does now, maybe the individual rows of the list should slide to their new positions.  That gives a person's eye the visual feedback, "Wait, don't click just now."  Animation is sort of the computer equivalent of what usually helps avoid this problem in real-life scenarios: Most of the time, the fact that you can see the other person moving and adapt to their movement gives your brain enough time to avoid a collision.
2. Maybe disable the mouse (and keyboard if appropriate) for a fraction of a second, e.g. maybe 1/4 second, immediately after a change, e.g. immediately after the list of chess tables was updated, or immediately after a program opens a new window or dialog.

Of course, it would often be appropriate to combine both of those techniques: disable the mouse, do the animation, and then re-enable the mouse.  If done that way, the mouse could be immediately re-enabled when the animation was done -- no need to wait for 1/4 second more after the animation is done, because the person has already had sufficient time to process what is happening and avoid an accidental click.

What do you think?  I'm sure none of this is terribly original -- I imagine lots of research on this topic has been done.  I just haven't come across it.  (Sometimes blogging scares me, because the Internet is so huge that no matter how original a particular thought of mine might be, the odds are extremely good that someone else has already had it, and has said it on the Internet, and thus it's already in the Google index, and so should I really bother.  Reminds me of a joke that A. Whitney Brown made many many years ago in Saturday Night Live: "There are a billion people in China.  Think about that.  That means if you're a one-in-a-million kind of guy, there are a thousand other people exactly like you.")