Command-Line Debugger for Free MXMLC Flash Development (Bonus: Batch File / Bash Script Basics)

Sep 30, 2011

Last year I put together tutorials on how to develop Flash games (and .swf applications in general) without using the pricy Flash animation software. I divided these tutorials into three sections:

Part 1: $0 Flash Development (free command-line Flash compilation of .as files)

Part 2: Flash Game Core Tutorial (images, input, audio, collision, real-time updates)

Part 3: Motion Tutorial (button-like key handling, move-to-click, gravity bounce)

Part of what I wrote for the first one of those, which will be especially useful to understand the content that follows, is the basic command-line skills tutorial. That tutorial splits partway through into Windows and Mac/Linux, since mxmlc works on either. To adapt the example batch/bash scripts included here to recompile your code with a simple double-click, you’ll need to know your way around the command-line of your OS using cd and dir or ls.

The above walkthroughs are all very basic. They barely scratch the surface of ActionScript 3 and command-line functionality. Similarly, this entry will only cover how to open the debugger to immediately benefit from AS3 trace lines and improved crash/error feedback. There is a lot to learn about debugging that will not be covered in this entry, but Googling can help take it from here. Much like starting up a helicopter, if done thoroughly simply getting started can be fairly involved in itself.

Likewise batch files (and especially bash scripts for Mac/Linux) can become surprisingly complex and powerful, bordering on simple meta-programs in their own right. Their inclusion and explanation here is at a shallow-but-functional sample depth, just as little as is needed for the purpose at hand.

Length Disclaimer

This entry looks long, judging by the scrollbar alone, however 40% of what follows does not apply to any given reader. Part of this entry is nearly duplicated, since details differ based on whether you are developing on a Windows PC or in Mac/Linux.

Additionally, there are only a few major steps. Most of the information here explains how it works and fits together, so that the individual aspects can be adapted or put to different use later. By no means should the amount of text here be taken to imply that opening the debugger involves a lot of work; the end result is actually a double-clickable icon that will automatically recompile your application and, if it compiled without errors, automatically start the debugger.

Intended Audience

This entry is in the Intermediate category. Although I am attempting to write this tutorial to be useful without any specific background, this will be much easier to follow if you have already created some Flash programs via command-line without using the debugger, or perhaps have used a debugger in another programming language/environment.

If you are starting to develop more complex AS3 programs that compile fine but don’t seem to work as expected, or moving to ActionScript 3 from another programming language (C, for example) and feeling held back by lack of error messages and debugging tools, this will get the ball rolling. Batch/script files are included only as a convenience to reduce typing and improve iteration time during development.

To try out the contents of this tutorial immediately, you’ll need a folder with working ActionScript 3 code already in it. Source code from any of the introductory mxmlc examples that I provide above (Parts 1, 2, or 3) will work fine, or you can use your own. If you’re feeling ambitious and ready to jump into the deep end a bit, to experiment with a large enough program for trace statements and detailed error messages to easily make this extra trouble worthwhile, you can also go download the source code for Everyone’s Platformer to try out here.

Why Is(n’t) This Covered

Debuggers are a fundamental and common part of programming for many types of software development – absolutely necessary for utilities applications, low-level hardware support (e.g. printer drivers), and nearly any programs developed at a commercial scale. As such, software engineers or students of computer science may be inclined to roll their eyes over the need for an entry like this to even exist. In many cases they learned to use debuggers at the same time that they learned how to program, or very shortly thereafter, and may be surprised that anyone can do much of anything with code without having a functional understanding of debuggers, like an extreme version of hearing that someone drives without ever looking at their dashboard for feedback on speed, fuel remaining, engine lights, etc. They’re used to developing software where much of the complexity is hidden, if you’ll excuse an overextended metaphor, under the hood.

However because videogame making inherently involves a ton of simultaneous, rich output (graphics position/rotation/speed, sound playing, immediate response to real-time input, discrete outcomes like HUD changes or entity creation/destruction…), and because gameplay programmers can often lean on established libraries to handle our deeper routines like memory blits, format imports, and network calls, hobbyist and self-taught game developers can actually produce some fairly impressive results in 2011 without ever using a debugger. The compiler provides sufficient error feedback when code doesn’t compile, and when it does compile, we’re often able to diagnose what might be wrong simply by observing how things in our games behave incorrectly. It’s like many of us are just concerned with how the car looks and feels to drive, and as long as it’s doing what we think it should, we’ll pay no more attention to what’s happening under the hood than the average consumer does.

Nevertheless, especially when working on increasingly complex or large games, or when working with someone else’s game code that you’re unfamiliar with, knowing what a debugger is and how to use it can save a ton of time in diagnosing mysteries that aren’t trivially observable as strange in-game functionality.

A Brief Aside for Experts

If you’re among the developers already comfortable with command-line, batch/script files, and one or more debuggers from other programming languages, and all you’re looking for is to be pointed in the right direction to figure it out on your own from there, the debugger program you’re looking for is fdb in the same flex_sdk\bin\ directory as mxmlc. Here’s Adobe’s guide to commands for it. Remember to add the -debug=true argument to your mxmlc line when compiling the .as file(s) into your .swf

As for everyone else, read on…

What a Debugger Does

Short and sweet: a debugger is a program that attaches to the latest version of the program you compiled (the .swf, in the case of AS3/Flash) to make error diagnosis easier. The debugger can assist in that goal a number of ways, such as stopping an application at some point then advancing one instruction at a time, or exposing variable values and program state while it’s paused. The most basic benefits, covered here, are better error messages (instead of silently acting strangely, or crashing completely) and exposing trace (“log”) text lines to yield clues about program flow or the values of otherwise unexposed variables.

What is a Batch File / Bash Script

Anything that can be done via command-line can be done with a batch file (Windows) or bash script (Mac/Linux), which can then be clicked on as an icon in the general operating system’s file navigation instead of typing commands in every time. This makes it easier to include a long chain of arguments and/or relative directory offsets that we know we’ll need to use every time. This also simplifies running a series of command-line operations when we otherwise would need to enter many lines in sequence.

Both types of scripts also offer ways to control flow of execution, so that we’ll be able to branch to different commands based on the outcome of another command-line program. An example of that will be included here. In particular, we’ll check to see whether the compiler ran into any errors, and skip running the debugger in that case since the compiler errors mean that the new up-to-date swf won’t be generated reflecting the latest code (every compiler error needs to be addressed before the debugger will be useful).

OS-Specific

What follows depends upon whether you’re on PC (Windows, with a DOS-like command-line) or Mac/Linux (Terminal command-line). If you’re on the latter, skip this upcoming Windows section, and you’ll find the information for those operating systems further below.

On the other hand, if the Windows section is what you need, after making it through continue past the Mac/Linux section for a few more tips and explanations that apply the same to any OS.

PC/Windows Section

First, if you have not done so already, please act on step 1 in this older HGD entry to expose filename extensions. Doing this is different depending on operating system version, but it’s worth Googling and fiddling with your Windows folder settings until this is fixed. If attempting to save a text file as “recompile.bat” gets intercepted by your plain text editor and renamed to “recompile.bat.txt”, if file extensions are still hidden that second filename will show up in Windows as “recompile.bat” but not work (since it really still ends with .txt), and that sort of problem can become a source of significant frustration. Programmers need to be able to see file extensions.

Using the debugger can be done completely via command-line. The debugger program is called fdb and is in the same directory as the mxmlc compiler. However to reduce the amount of typing needed we’ll be setting up a batch file.

To create the batch file, first create a new plain-text file – i.e. use a simple text editor like Notepad, Metapad, or Notepad++, or whatever program you’re using to edit .as files, but not a full word processor like Microsoft Word. Word processors tend to save a ton of hidden formatting characters that would mess up the batch file. Go ahead and save the new, blank text file as “recompile.bat” in the directory where the Flex SDK is installed (one folder higher than the bin\ folder that has mxmlc in it – for example, mine is c:\flex_sdk\). With some simple modifications this .bat file can live in any directory where it will be most convenient, but for consistency at this stage create the file there.

As a reminder from earlier: make sure at this point that you have Windows set to show file extensions (that is, to not “hide known-file extensions”), and check to make sure that the text editor didn’t automatically renamed the file to recompile.bat.txt, which would prevent Windows from recognizing it as a batch file. This can be avoided by fiddling with the Save As File Type drop-down box to support generic files *.* instead of text document *.txt, though if it already got saved and had to be manually renamed to .bat after saving, right click on that file and choose edit to open it in Notepad.

Now to fill in the file, copy/paste the text from below that’s shown in system font. I have color coded a couple of sections that will need particular attention. Namely:

The red text below doesn’t need to be red (of course – plain text files can’t do that), I’ve colored it to signify that it’s all the same line, wrapped here to fit the width of this blog’s text column. Don’t separate it across multiple lines as it is here – the whole red/purple chunk is a single long statement for calling mxmlc and passing 5 command-line arguments.

Purple text likewise shouldn’t actually be purple in your batch file. That’s just my way of marking which text you’ll likely need to adjust to work for your project, for example swapping in either the name of your project’s folder, primary ActionScript file, or appropriate relative directory structure.


@ECHO OFF
bin\mxmlc projects\SmokingBricks\Main.as -managers=flash.fonts.AFEFontManager -static-link-runtime-shared-libraries -debug=true
IF %ERRORLEVEL% NEQ 0 GOTO ERRORS
ECHO.
ECHO ----------------------INSTRUCTIONS----------------------
ECHO Compiled, now running...
ECHO Type "continue" - no quotes - followed by return to start
ECHO Note: May need to do "continue" command twice, for preloader
ECHO Type "quit" - no quotes - followed by return key to exit
ECHO.
ECHO.
bin\fdb projects\SmokingBricks\Main.swf
GOTO END
:ERRORS
ECHO.
ECHO -------------------INSTRUCTIONS-------------------
ECHO Found %ERRORLEVEL% error(s) during compilation
ECHO Fix the errors indicated above then try this again.
ECHO.
ECHO.
pause
:END
ECHO Done. Feel free to close this Window if it hasn't already closed automatically.

Adapting For Your Project

I keep all of my work in per-project subfolders of a projects directory that I create within my Flex SDK folder. In other words, my file arrangement looks something like this:

c:\flex_sdk\bin\mxmlc.exe
c:\flex_sdk\projects\SmokingBricks\Main.as

For organizational reasons, I suggest a similar directory structure, but as long as your change the purple text in your batch file to reflect your own project names, relative folder positions, and the name of your main ActionScript file, you’ll be in good shape. Main.as is the name of the main ActionScript file for the project I wrote this for, SmokingBricks is the name I gave the folder where I keep all source and assets for that particular project, and projects\ is the folder I made to contain my various project folders.

Using the Batch File

Double click on the recompile.bat file you’ve saved, and it should immediately open up a new DOS-style command-line box. It will then attempt to recompile your program. If compilation succeeds, it will drop you off in the debugger. Type “continue” (no quotes, or “cont” for short will also work) and press return to start the program. If compilation fails, the DOS-style window will indicate how many compilation errors were encountered, what those errors were, and pause until a key is pressed.

If the terminal window, instead of recompiling and entering the debugger, displays “program not found”, “directory not found”, or something of the sort, double check that the directory paths and file names marked in purple have been correctly changed to point to your project’s files. (Yours are not very likely to be “projects\SmokingBricks\Main.as” and “projects\SmokingBricks\Main.swf”. Be sure too that you have not mixed up the .as extension for compilation, compared to the .swf extension for attaching to the debugger.)

Explanation of Elements

@ECHO OFF – This hides the batch file’s lines, instead only showing the output of programs and commands executed. To better understand what it does, try deleting this line and running the batch file again. It should still work, but you’ll see a lot more redundant junk displayed, reflecting the literal contents of the batch file.

bin\mxmlc projects\SmokingBricks\Main.as
-managers=flash.fonts.AFEFontManager -static-link-runtime-shared-libraries
-debug=true
– The bin\mxmlc part runs the mxmlc.exe program (our Flash compiler that converts .as text code to a .swf Flash program) in the bin folder one deeper than the folder that contains this batch file. The projects\SmokingBricks\Main.as refers to the primary ActionScript file for the project, also relative to the directory location of the batch file. “-managers=flash.fonts.AFEFontManager” allows you to embed fonts in the swf, but keeping it there even when you aren’t embedding fonts is handy so you won’t go crazy when otherwise correct font embedding code you add on a whim mysteriously won’t work. “-static-link-runtime-shared-libraries” is necessary for slightly strange technical reasons – if it’s not there, you’ll receive a scary sounding warning from the compiler to add that argument, and when the swf opens it will instantly crash (go blank). The “-debug=true” argument has to be added to the end for information that our debugger needs to be compiled into the application – without it fdb would just launch the swf without any of the useful debugger functionality working.

The order of arguments, after the target file name, is unimportant.

IF %ERRORLEVEL% NEQ 0 GOTO ERRORS and :ERRORS – This is a conditional jump, which can be used in a batch file to skip over arbitrarily many lines based on how the last run program left %ERRORLEVEL%. %ERRORLEVEL% is a somewhat archaic but still useful way for local applications to leave some hint about their exit condition, it’s the output-side to go along with command-line arguments as the input-side, and especially comes in handy for a batch file like this one. NEQ is short for “not equals”, and mxmlc sets %ERRORLEVEL% to the number of errors encountered by the compiler. If there are 0 errors the code drops through to the part that opens the debugger, whereas if there are 1 or more errors the code skips to the part displaying error count and bailing out.

Note that “ERRORS” here is just an arbitrary label – as long as it is changed to the same word both after GOTO and after the : on the later line, the batch file should still work exactly the same. Just like with variable and function names, picking a meaningful name is a good way to self-document intended functionality and minimize the chance of name collision.

GOTO END and :END – This goto step is not connected to any conditional, but notice that due to its position it will only be reached if the debugger has already run, which as just explained means that no errors were found during compilation. This jump is then used to skip over the error summary message that is intended only for when compilation errors are found.

ECHO [followed by anything] – These lines output arbitrary strings of text to the command-line environment, so that we can openly announce what’s happening in the batch file as it runs. Variable names are supported in this, as shows up in the later line, “ECHO Found %ERRORLEVEL% error(s) during compilation”.

bin\fdb projects\SmokingBricks\Main.swf – This opens up the Flash debugger, fdb, located relative to this batch file in the bin\ folder, attached to the program swf that we just compiled, i.e. the one corresponding to the relative directory and particular filename we passed mxmlc earlier in the batch file.

As with practically anything typed inside a batch file, if you’re at command-line and navigate to the directory in which this batch file is placed, you could just type that exact command, and in that one step the Flash debugger will launch attached to that swf. By doing it with this batch file instead though, we’re saving a bunch of typing each iteration, removing the risk of typos every time, and ensuring (via the earlier GOTO statement) that we’re only using the debugger if the mxmlc compiler successfully recompiled the swf. That last point is particularly important, as one common source of horrible frustration during debugging can be trying to fix a swf and iteratively saving code changes, not noticing (perhaps due to particular IDE layout, a separate batch file made for compilation only, or some other faulty custom arrangement) that the swf isn’t even changing between code updates.

pause – Blocks the batch file’s execution until the user presses any key. This is important near the end of batch files that produce text output needing to be read (such as the compiler error messages or echo lines), since otherwise the DOS-style window will typically close itself once it finishes executing the last command.

Example Output

Successful example output:

Loading configuration file C:\flex_sdk\frameworks\flex-config.xml
C:\flex_sdk\projects\SmokingBricks\Main.swf (30164 bytes)

----------------------INSTRUCTIONS----------------------
Compiled, now running...
Type "continue" (no quotes) followed by return to start
Type "quit" (no quotes) followed by return key to exit

Adobe fdb (Flash Player Debugger) [build 12683]
Copyright (c) 2004-2007 Adobe, Inc. All rights reserved.
Attempting to launch and connect to Player using URL
projects\SmokingBricks\Main.swf
Player connected; session starting.
Set breakpoints and then type 'continue' to resume the session.
[SWF] C:\flex_sdk\projects\SmokingBricks\Main.swf - 50,694 bytes after decompression
(fdb)

Once that prompt is displayed, type in “continue” (without quotes) then return:

(fdb) continue
[trace] program started
[SWF] /my/core.swf - 1,633 bytes after decompression

At that point the program will open in a separate window. To get that line “[trace] program started” to display, I added this single line of ActionScript 3 code early in the source, in the program’s constructor, before I ran the batch file to compile and debug:

trace("program started");

Windows Wrap Up, Immediate Benefits

That trace command is quite useful, and one of the reasons to open your Flash swf in the debugger instead of on its own. More on that after the Mac/Linux Section.

The other immediate value of opening the swf in the debugger is that if something goes wrong, instead of the program doing its best to function anyway (as it would if running in a browser or the standalone release Flash player), the debugger window will display detailed error information.

There are many useful commands that can be used within the debugger to perform such actions as pausing the swf, advancing logic one step at a time, inspecting values in memory, etc., but for now learning about those is left as an exercise for the reader.

As an easy next step, make a copy of the batch file and name it “recompileNoDebug.bat” and edit out the “-debug=true” argument from the bin\mxmlc line. The new batch file should now open the swf instantly if it compiles, without needing to type in the “continue” command, since it won’t be attached to the fdb debugger (only launched by it). This of course means no trace lines nor error messages on partial crashes, but for quicker surface-level revisions when the debugger isn’t needed to investigate deeper issues, this alternative recompilation file may save another 10 seconds or so per iteration.

At this point, unless you are curious to browse the Mac/Linux section for comparison, please continue on to the brief section on trace at the end of this post.

Mac/Linux Section

Create a new text file in a plain-text editor – i.e. Text Edit or Text Wrangler, or whatever program you’re using to edit .as files, but not Microsoft Word, Pages, or OpenOffice.

Go ahead and save the new, blank text file as “recompile.command” in the directory where your project files are. My suggested relative positions that I’m assuming in the example here are:

~/Desktop/as3Dev/bin/mxmlc
~/Desktop/as3Dev/projects/SmokingBricks/recompile.command

I renamed my flex_sdk/ folder to as3Dev/, but as long as they’re the right relative depth from one another, the folder names won’t actually matter in this case. For that matter, with some simple modifications this .command file can live in any directory where it will be most convenient, but for now in my example it’s going in the relative position indicated above.

Now to fill in the file, copy/paste the text from below that’s shown in system font. I have color coded a couple of sections that will need particular attention. Namely:

The red text below doesn’t need to be red (of course – plain text files can’t do that), I’ve colored it to signify that it’s all the same line, wrapped here to fit the width of this blog’s text column. Don’t separate it across multiple lines as it is here – the whole red/purple chunk is a single long statement for calling mxmlc and passing 5 command-line arguments.

Purple text likewise shouldn’t actually be purple in your batch file. That’s just my way of marking which text you’ll likely need to adjust to work for your project, for example swapping in either the name of your primary ActionScript file or appropriate relative directory structure. The right number of ../ before the mxmlc and fdb program calls depends on how many directories deep your source file is relative to the flex_sdk/bin folder – i.e. is the file inside a flex_sdk/projects/ folder (one ../), or a flex_sdk/projects/myGame/ folder (use ../../ as is shown here), or a flex_sdk/projects/myGame/src folder (../../../), etc.

#!/bin/bash
cd "`dirname "$0"`"
../../bin/mxmlc ./Main.as -static-link-runtime-shared-libraries
   -managers=flash.fonts.AFEFontManager -use-network=false
   -debug=true
ERRORLEVEL=$?
if [ $ERRORLEVEL -eq 0 ]
then
  echo 
  echo ----------------------INSTRUCTIONS----------------------
  echo Compiled, now running...
  echo Type \"continue\" - no quotes - followed by return to start
  echo   Note: May need to entry \"continue\" command twice
  echo Type \"quit\" - no quotes - followed by return key to exit
  echo 
  echo
  ../../bin/fdb ./Main.swf
else
  echo 
  echo -------------------INSTRUCTIONS-------------------
  if [ $ERRORLEVEL -eq 1 ]
  then
    echo Found $ERRORLEVEL error during compilation
  else
    echo Found $ERRORLEVEL errors during compilation
  fi
  echo Fix the errors indicated above then try this again.
  echo 
  echo
fi

echo
echo Done. Feel free to close this window.
echo

Making the File Double-Clickable

As a slight inconvenience, we’ll need to modify the owner/permissions of the new .command file in order to make it support double-click operation. The “Get Info” window in Mac OS only shows Read & Write permissions, but we’ll need to set the Execute permission, which we’ll be able to do with the chmod command via Terminal.

First, navigate in Terminal using cd commands to the project directory containing the new recompile.command file. Then run the following command in the directory:

chmod 755 recompile.command

After doing this, you’ll be able to double click the recompile.command file in that directory to execute the bash script.

This step can be avoided in the future by simply copy/pasting your .command file and making edits to it for each project, since duplicating the file preserves the ownership permissions set on it.

Using the Bash Script

Double click on the recompile.command file you’ve saved, and it should immediately open up a new Terminal window. It will then attempt to recompile your program. If compilation succeeds, it will drop you off in the debugger. Type “continue” (no quotes) and press return to start the program. If compilation fails, the Terminal window will indicate how many compilation errors were encountered, what those errors were, and pause until a key is pressed.

If the terminal window, instead of recompiling and entering the debugger, displays “program not found”, “directory not found”, or something of the sort, double check that the directory paths and file names marked in purple have been correctly changed to point to your project’s files. (Yours are not very likely to be “Main.as” and “Main.swf”, and may or may not be relative to the bin directory by two exactly directory depths, i.e. “../../”. Be sure too that you have not mixed up the .as extension for compilation, compared to the .swf extension for attaching to the debugger.)

Explanation of Elements

#!/bin/bash – This specifies the type of script used in this file.

cd “`dirname “$0″`” – This changes the active directory to the one in which the .command script file is run from.

../../bin/mxmlc ./Main.as
-managers=flash.fonts.AFEFontManager -static-link-runtime-shared-libraries
-debug=true
– The ../../bin/mxmlc part runs the mxmlc.exe program (our Flash compiler that converts .as text code to a .swf Flash program) in the bin folder two directories up from the folder that contains this bash script. The ./Main.as refers to the primary ActionScript file for the project, which here is assumed to be in the same directory as the .command file. “-managers=flash.fonts.AFEFontManager” allows you to embed fonts in the swf, but keeping it there even when you aren’t embedding fonts is handy so you won’t go crazy when otherwise correct font embedding code you add on a whim mysteriously won’t work. “-static-link-runtime-shared-libraries” is necessary for slightly strange technical reasons – if it’s not there, you’ll receive a scary sounding warning from the compiler to add that argument, and when the swf opens it will instantly crash (go blank). The “-debug=true” argument has to be added to the end for information that our debugger needs to be compiled into the application – without it fdb would just launch the swf without any of the useful debugger functionality working.

The order of arguments, after the target file name, is unimportant.

ERRORLEVEL=$? – In a Bash Script, programs leave a value to the next program run, which can be accessed as $?. Because various other evaluative statements or program calls may change this value, here we save it as a variable name (ERRORLEVEL) so that we can refer to it throughout the script without wondering whether $? has been changed by some other line of the script. Note that since it is a variable label, ERRORLEVEL can be practically any arbitrary word, so long as where it appears elsewhere in the file the same term is used.

The $? mechanism is a somewhat archaic but still useful way for local applications to leave some hint about their exit condition. It is the output-side to go along with command-line arguments as the input-side, and especially comes in handy for a batch file like this one.

if [ $ERRORLEVEL -eq 0 ] and then and else and fi – This is a conditional if-else statement, which can be used in a bash script to switch between arbitrarily many lines based on the evaluation of some value (here $ERRORLEVEL). -eq is short for “equals”, and mxmlc leaves $? set to the number of errors encountered by the compiler. So if there are 0 errors the code goes through to the part that opens the debugger, whereas if there are 1 or more errors the code skips to the part displaying error count and bailing out.

then is necessary on the line following the if condition. fi is used to mark the end of the if-else chain.

Another simple example of using the if-then-else-fi structure, demonstrating nestling, is shown to distinguish between whether to report the number of “errors” found during compilation or the “error” found during compilation (depending upon whether $ERRORLEVEL -eq 1).

echo [followed by anything] – These lines output arbitrary strings of text to the command-line environment, so that we can openly announce what’s happening in the bash script as it runs. Variable names are supported in this, as shows up in the later line, “echo Found $ERRORLEVEL errors during compilation”.

../../bin/fdb ./Main.swf – This opens up the Flash debugger, fdb, located relative to this bash script two folders up then in the bin/ folder, attached to the program swf that we just compiled, i.e. the one corresponding to the particular filename we passed mxmlc earlier in the batch file.

As with practically anything typed inside a bash script, if you’re at command-line and navigate to the directory in which this bash script is placed, you could just type that exact command, and in that one step the Flash debugger will launch attached to that swf. By doing it with this bash script instead though, we’re saving a bunch of typing each iteration, removing the risk of typos every time, and ensuring (via the earlier if-then-else-fi mechanism) that we’re only using the debugger if the mxmlc compiler successfully recompiled the swf. That last point is particularly important, as one common source of horrible frustration during debugging can be trying to fix a swf and iteratively saving code changes, not noticing (perhaps due to particular IDE layout, a separate bash file made for compilation only, or some other faulty custom arrangement) that the swf isn’t even changing between code updates.

Example Output

Successful example output:

/Users/deleonic/Desktop/as3Dev/projects/SmokingBricks/recompile.command ; exit;
Christopher-DeLeons-MacBook-Pro:~ deleonic$ /Users/deleonic/Desktop/as3Dev/projects/SmokingBricks/recompile.command ; exit;
Loading configuration file /Users/deleonic/Desktop/as3Dev/frameworks/flex-config.xml
/Users/deleonic/Desktop/as3Dev/projects/SmokingBricks/Main.swf (35334 bytes)

----------------------INSTRUCTIONS----------------------
Compiled, now running...
Type "continue" - no quotes - followed by return to start
Note: May need to entry "continue" command twice
Type "quit" - no quotes - followed by return key to exit

Adobe fdb (Flash Player Debugger) [build 14159]
Copyright (c) 2004-2007 Adobe, Inc. All rights reserved.
Attempting to launch and connect to Player using URL
./Main.swf
Player connected; session starting.
Set breakpoints and then type 'continue' to resume the session.
[SWF] Users:deleonic:Desktop:as3Dev:projects:SmokingBricks:Main.swf - 64,989 bytes after decompression
(fdb)

Once that prompt is displayed, type in “continue” (without quotes) then return:

(fdb) continue
[trace] program started

At that point the program will open in a separate window. To get that line “[trace] program started” to display, I added this single line of ActionScript 3 code early in the source, in the program’s constructor, before I ran the bash script to compile and debug:

trace("program started");

Mac/Linux Wrap Up, Immediate Benefits

That trace command is quite useful, and one of the reasons to open your Flash swf in the debugger instead of on its own. More on that after this section.

The other immediate value of opening the swf in the debugger is that if something goes wrong, instead of the program doing its best to function anyway (as it would if running in a browser or the standalone release Flash player), the debugger window will display detailed error information. Use the bt (backtrace) command at the debugger’s prompt after a fault to get line numbers and function names that led to the error.

There are many useful commands that can be used within the debugger to perform such actions as pausing the swf, advancing logic one step at a time, inspecting values in memory, etc., but for now learning about those is left as an exercise for the reader.

As an easy next step, make a copy of the bash script and name it “recompileNoDebug.command” and edit out the “-debug=true” argument from the ../../bin/mxmlc line. The new bash script should now open the swf instantly if it compiles, without needing to type in the “continue” command, since it won’t be attached to the fdb debugger (only launched by it). This of course means no trace lines nor error messages on partial crashes, but for quicker surface-level revisions when the debugger isn’t needed to investigate deeper issues, this alternative recompilation file may save another 10 seconds or so per iteration.

Using Trace Lines (Applicable to All)

There are two easy ways to benefit from trace() calls: exposing values in a nicely formatted way, and determining program flow. To expose values easily in a trace statement, remember that in ActionScript 3 it’s easy to concatenate a string that includes variables of all basic types, i.e. trace("x is "+p1.x+" and y is "+p1.y);

To expose the program flow, simply add trace statements into the start and/or end of various function calls in question, for example trace("init() enter"); and trace("init() exit");, so that starting the application will instantly create a trail of which functions executed in which order. This approach can be handy if you’re working with someone else’s code other than your own, or your own code from long ago, and having trouble determining which order the many early function calls are made. This method can also easily answer, with absolutely certainty, whether a function that you expect to be called somewhat rarely is ever being called at all, and so on.

Closing

There is still much to be learned about debugging from where this entry leaves off. As linked to earlier in the Expert Aside, here is Adobe’s guide to commands for fdb, if you’re curious to explore and experiment with some of the available commands.

At the very least though, even by trace() output and improved crash errors, you’ll hopefully now be able to untangle problems that previously proved frustrating to diagnose by real-time observation alone. Additionally, I hope that the starting example of a batch file / bash script provided may prove handy in reducing the monotony potentially involved in debugging free command-line Flash projects.



Learn and practice team game development with Gamkedo Club.
Membership worldwide. Professional support. Proven process.




Subscribe by e-mail to receive weekly updates with Gamkedo.Community interviews and YouTube training videos for game developers!



One Comment

  1. […] Recompilation Scripts, Opening the Debugger – Using scripts for recompilation, and getting started with the command-line debugger […]

Leave a comment

Comments Form
  • Your email will not be used for any purpose other than to update you in replies to your comments. Your website address will be shown as a link from your name with your comment. Your profile photo is auto-magically provided by Gravatar.

All contents Copyright ©2017 Chris DeLeon.

Site production by Ryan Burrell.