Debugging production ready AIR applications

One of the biggest problems around testing installed AIR applications is that testers can’t see when a runtime exception is triggered. Lots of times the symptom of a problem will be something completely different to the real cause and developers will have to spend much more time trying to figure out what was the root cause of the problem. Even though you have a good logging policy if there’s an uncaught exception there’s not too much you can do.

Here are some techniques I’ve came across to make testing less painful for everybody.

The debug flag way

One thing I’ve been thinking for a while is that there are not two different versions of the AIR runtime; one with debugging enabled and the other without it (the way Flash Player has). This means that there might be a way to enable and disable debugging in the same runtime. This would allow, at least in some controlled environments, to see Runtime Exceptions and make everybody’s life easier. At least until we have global error handling implemented directly on AIR or Flash Player. Yes, I agree, It’s unbelievable that on its 10th version we still are not able to capture global exceptions: FP-444 and FP-1499

Using Procmon I realized that when an AIR application is launched it tries to read a file in {INSTALLATION_FOLDER}/META-INF/AIR/debug. See the screenshot. What surprised me was the result “NAME NOT FOUND”. Basically the file didn’t exist in the app I was playing with. After some more trial / error, yes, you’re right, this is the flag that switches on and off debugging capabilities.

If an AIR application is launched and an empty file with name debug is found in {INSTALLATION_FOLDER}/META-INF/AIR/debug then, any runtime exception will be displayed in a system modal window! In OS the path for this file will be {APPLICATION_FOLDER}.app/Contents/Resources/META-INF/AIR/debug

So if testers (or users during the earlier versions of your app) are using your application, make sure they create the debug file and attach any stack trace they see to their bug reports.

The adl way

This is not as easy as the previous solution but it gives the testers more options.

Once installed, an AIR application, is not more than the swf file produced from FB, its application descriptor and a native launcher. Given that we have access to the main application swf file and its corresponding descriptor we can use ADL to launch the installed application instead of the native launcher.

Here’s how:

1. Installed the SDK you want to use from http://opensource.adobe.com/wiki/display/flexsdk/Downloads
2. Uncompress the zip in the location you prefer. I’ll refer to this folder as {FLEX_HOME}

In Windows
3. Right click on “My Computer” > Properties
4. Go to “Advanced” tab
5. Click in the option “Environment Variables”
6. In the “System variables” find the “Path” definition and add this to it (double clicking on it): “;{FLEX_HOME}/bin”
7. Make sure your replace {FLEX_HOME} with the path to the folder where you’ve uncompressed the SDK

In OS X
3. Open a terminal
4. Execute this command: open ~/.bash_profile
5. Add the following line to the opened file:
PATH=${PATH}:{FLEX_HOME}/bin
6. Make sure your replace {FLEX_HOME} with the path to the folder where you’ve uncompressed the SDK

In Linux
3. Open a terminal
4. Edit your profile file ~/.profile
5. Add the line: export PATH=$PATH:$FLEX_HOME

Then to launch the application you will have to:

In Windows
1. Open a command line window. Start > “Run …” > cmd
2. Navigate to the folder where the application is installed: cd “Program Files”/MyApp
3. Execute this command: adl META-INF/AIR/application.xml .
4. Don’t forget the dot at the end of the command

In OS X and Linux
1. Open a terminal
2. Navigate to the folder where the application is installed: cd /soft/testAirApp.app/Contents/Resources where testAirApp is the name of your application
3. Execute the following command: adl META-INF/AIR/application.xml .
4. Don’t forget the dot at the end of the command

If during the execution process there’s an exception, ADL will show it.

12 Comments to “Debugging production ready AIR applications”

  1. Debugging AIR applications « Enrique Duvós – RIA Excellence in Europe

    [...] article from Xavi Beumala, Senior Architect at Adobe Consulting, on debugging production ready AIR [...]

  2. Tom Chiverton 17 August 2009 at 3:37 pm #

    On Linux, you need too add
    export PATH=$PATH:$FLEX_HOME
    to ~/.profile

    The adl command is the same, though you’ve left the dot off the end of the OSX version :-)

  3. xbeumala 18 August 2009 at 4:29 am #

    Hey Tom!
    Thanks for the typo and the Linux steps, I’ve added them to the post

  4. Joan Garnet 27 August 2009 at 2:06 am #

    I already voted for those feature requests. They are a must in a platform such as Flash.
    In the meantime wow… that trick can definitely safe a developer’s life :)

    Cheers!

  5. Global Exception Handling / Crash Reporting in Adobe AIR – Partially Solved?

    [...] will happily pop up an ActionScript error box, complete with stack trace, in case of an exception. Zavi discovered this by using Procmon, which is an excellent [...]

  6. mescolar 22 September 2009 at 10:06 am #

    Hey Xavi!
    Useful tricks. I have tested the two solutions and now I can see some masked errors.
    Only a commentary, in “{INSTALLATION_FOLDER}/APP-INF/AIR/debug” would be advisable to change APP_INF by META-INF.

  7. xbeumala 22 September 2009 at 11:01 am #

    Thanks Mike,
    post updated :)

  8. lessrain blog » Blog Archive » Intercepting Runtime Errors in installed AIR applications

    [...] After Googling a bit we found a couple of interesting solutions for this problem provided by Xavi Beumala in his blog: Debugging production ready AIR applications [...]

  9. Global Exception or Error Handling in Flex | rialvalue.com

    [...] Debugging and getting Stack-trace error dialogs with installed AIR applications [...]

  10. matteosistisette 20 July 2010 at 6:20 pm #

    Hi,

    I had already used the “debug flag” way in Windows, but I cannot get it to work in Linux.

    I found out the installation directory is /opt/(applicationname), and there is a
    /opt/(applicationname)/share/META-INF/AIR/ directory.
    I’ve tried creating an empty file named “debug” inside that directory, but it doesn’t work.
    I also tried creating an empty directory named “debug” (which is what worked in Windows), but nothing.

    Does anybody know where do I have to create the “debug” file in Linux??

    thanks
    m.

  11. matteosistisette 20 July 2010 at 6:44 pm #

    Hi again,

    I tried launching my air application with
    sudo strace -o logfile -e trace=file /opt/liveindexor/bin/xxxxxxx

    and I looked into the geneeated log file, but I didn’t find any occurrence of the word “debug”.

    Does it mean that there is no debug flag at all in Linux and there is no way to use debug mode without using adl??

    thanks
    m.

  12. don_loqheart 6 July 2011 at 7:51 pm #

    Does this still work? I’m running AIR 2.7, trying to debug my production app, and it doesn’t work for me. I tried checking procmon and couldn’t find AIR\debug being accessed.


Leave a Reply