Debugging Flash / Adobe Flex 2 / ActionScript 3 code using fdb on Mac or Windows is not exactly a straightforward affair. The following are instructions on how to get fdb running for debugging flash files and how to debug flex through the command line tools.
Preamble:
- Verify that you have a debug capable version of Flash Player 9 (or more recent) on your Mac or Windows machine. You normally get this by default if you’ve installed the Adobe Flex SDK 2 or Adobe Flex Builder 2 / 3 (and have not installed/updated Flash Player since then). All web browsers that you had installed at the time of your Flex Builder / SDK installation should be updated with the Debugger versions of Flash Player 9. To check that your version of Flash Player is debug enabled, just open up any web page that has a flash component within it such as Google Finance and right click on the flash component within the browser window. You should see a context menu pop up with a “Debugger” menu item, which may or may not be greyed out.
- Verify that you have Adobe Flex SDK 2 installed or Adobe Flex Builder 2 / 3 installed (which contains the SDK as part of the Flex Builder install). If you’re on a Mac, the Adobe Flex SDK 2 is installed into /Applications/Adobe Flex Builder 2/Flex SDK 2, so open up Finder and check that you’ve got this Folder/directory available in /Applications.
- create a symbolic link to the fdb program:
sudo ln -s /Applications/Adobe Flex Builder 2/Flex SDK 2/lib/fdb.jar /usr/local/lib/fdb.jar
sudo ln -s /Applications/Adobe Flex Builder 2/Flex SDK 2/bin/fdb /usr/local/bin/fdb
The following example debugs a flash file named salesforce-debug.swf. Note that you don’t debug your regular production compiled flash file, you debug, the “debug” version, which is automatically created for you when you compile your flash file or project. These files are normally located within the /bin directory of your Flex project.
If the following example, when you see prompts such as ‘$’ or ‘(fdb)’, do not mistake them for commands, those are my prompts and you should be typing what follows those prompts. Lines not preceded by either a bullet or prompts are output from the fdb program.
To debug a Flash .swf using fdb on a Mac:
- launch the Terminal program (from /Applications/Utilities/Terminal)
- change directories / folders until you’re in the same directory as the .swf file you want to debug
- launch fdb
$ fdb
- when you start up fdb you should see an fdb prompt: (fdb)
- you need to specify the .swf file you want fdb to hook into and debug
(fdb) file salesforce-debug.swf
(fdb) run
Attempting to launch and connect to Player using URL
salesforce-debug.swf
Player connected; session starting.
Set breakpoints and then type ‘continue’ to resume the session.
[SWF] Users:ben:Documents:Flex Builder 2:salesforce:bin:salesforce-debug.swf – 1,101,498 bytes after decompression
- At this point a browser window should pop-up and begin to load your flash .swf file, but it will not finish loading until you’ve set your breakpoints and tell fdb to ‘continue‘. Setup your breakpoints now by using the ‘break’ keyword followed by a function name or a line number. In the following I set a breakpoint in my function ‘sfquery’ which will stop the Flash .swf when it hits this function and you’ll get a prompt in fdb debugger.
(fdb) break sfquery
Breakpoint 1 created, but not yet resolved.
The breakpoint will be resolved when the corresponding file or function is loaded.
- At this point the browser window with the half-loaded Flash file is still hung at “Loading…”. Repeat with as many breakpoints as you need. When done with breakpoints, you must issue a ‘continue’ command to get Flash to continue loading the .swf for debugging.
(fdb) continue
Additional ActionScript code has been loaded from a SWF or a frame.
To see all currently loaded files, type ‘info files’.
Resolved breakpoint 1 to salesforce.mxml:64
- Ok, this step is key to the debugging setup in Flex… you have to hit Return/Enter at an empty fdb prompt in order to get the your Flash file / Flex project to actually finish loading and to run in the browser window when in debug mode. No, there are no instructions for this, you just have to figure this out on your own through trial and error. Before this the browser window should have the Flash file running but frozen and “loading” until you hit the Enter key while in the fdb debugger, which is the next step:
(fdb) [hit the Enter button here at this blank prompt]
- Finally at this point your browser should finishing loading up the Flash file you’ve just set up for debugging and it should be ready for action. If you see a blank page that is still “loading”, go back into the Terminal and spank the Enter / Return button a few more times and see if the browser page responds by loading up your Flash debug file. Hopefully it does. And if it doesn’t, you’re back to square one. If you are reading this and have found other solutions to get fdb to actually work, please submit a comment and I’ll add it to this posting.
- Now when you use your .swf file and hit the function that you’ve set a breakpoint for as mentioned previously, the Flash program will freeze and when you go back to fdb in the Terminal window you should see something like the following:
[trace] Method name is: login
[trace] Method name is: login
Breakpoint 1, salesforce.mxml:64
64 private function sfquery():void {
(fdb)
- This is where you’ve hit paydirt. At this (fdb) prompt you can now start inspecting variables using ‘p’ <var_name>, step over lines using ‘n’, list lines of code with ‘l’, list previous lines of code with ‘l -‘, get help by typing ‘help’, step out of the current function with ‘finish’, and continue executing the program with ‘continue’.
- After you’re finished debugging the function you’re in, type ‘continue’ to return focus back to your web browser that is running your Flash program and this will return you back into normal running mode.
- To quit debugging just go into the Terminal running fdb and type ‘quit’
quit
Do you want to attempt to halt execution? (y or n)
- Enter ‘y’
Attempting to halt.
To help out, try nudging the Player (e.g. press a button)
Execution halted 00041994at 0xExecution halted 00041994 (268692)
- Just enter ‘quit’ again
The program is running. Exit anyway? (y or n)
- Enter ‘y’ again and you should be returned back to your Terminal prompt
That’s about it for getting the Flash Debugger to work in Mac OS X.
Here’s a useful page of fdb debugger commands to use while debugging Flex or debugging Flash .swf files.
Common errors when trying to debug Flash and Flex:
- A common error message with an incorrectly setup fdb flash debug session is the following: “A connection to the Debugger or Flash Player could not be established by Adobe Flash Player 9”. This happens when you simply start the debug version of a flash file, load up fdb, issue a ‘run’ command in fdb, then right click the Flash file and choose “Debugger” from the context menu. Although this would make a lot of sense in how to setup the command line debugger… it simply does not work this way.
- Another common error to see within fdb command line debugger itself is: “WARNING: The Player that you are using does not support all fdb commands.”. This is not the reason why you cannot debug in fdb. This warning message is only issued when you’ve setup an fdb debugging session incorrectly, like in the previous example.
- “Where is the debugger or host application running? Localhost or Other Machine” This is another question you should never see if you’ve setup your Flex debugging session correctly. Following the above step by step instructions for debugging a Flash / Flex project or file should avoid this error.
Good luck and let me know if you have any tips to add to this.
Leave a Reply