Debug AIR apps on Android with Flash Builder 4

Posted on June 28, 2010 | 10 comments

As the title says I am going to explain how to debug AIR applications in Flash Builder 4 that are running on an Android device.

Note: This is using AIR for Android prerelease off labs.adobe.com and the tooling and procedure to do on device debugging of AIR for Android with Flash Builder 4 will change in the future.

Source code for this post as a Flash Builder 4 project called DebugDemo.fxp.

There is a couple of steps to make this happen but the idea is broken down here:

• Connect Android device to same network as desktop with Flash Builder, and lookup the desktop ip address.
• Compile application for debugging and android permissions of INTERNET (see note below), both mxmlc and adt.
• Put the debug version of the application on the Android device.
• Configure the project in Flash Builder to launch debugger with out launching the Application.
• Launch newly configured project.
• Launch AIR application on the Android device.
• (depends if you use correct value in -connect with adt) Enter IP of Flash Builder machine and click button.

The Detailed Steps
I first made sure that my Google Nexus One made by HTC was connected to my local wifi network. Then I retrieved my desktop’s ip address of value 192.168.1.100, which I’ll use in a second.

There are various tools to do compiler and package your AIR applications for Android, but what I am showing is the lowest level options using mxmlc and adt. Both these tools are found in the Flex SDK, and more specifically with a Flex 4 SDK and AIR 2.5 SDK from the AIR for Android prerelease. If you are using Flash Professional CS5 the UI handles most of this for you, but you’ll still need the latest AIR for Android prerelease SDK.

NOTE: The AIR runtimes support android permissions per application. That means you will need to set the correct android permissions in the android manifest area of the your AIR application descriptor file. You will need the android permission of <uses-permission android:name="android.permission.INTERNET"/>. You will see an example AIR application descriptor file in the DebugDemo.fxp.

Before packaging the AIR for Android application with adt, you’ll need to create a debug swf. By default the Flash Builder creates a debug SWF in the “bin-debug” folder. You can use this version of the SWF in the packaging arguments of adt or if you are packaging with mxmlc from the command line all you need to add is “-debug=true” to the compiler arguments. Here is a part from my shell script (Mac OS X could be modified for Windows command line) compile.sh found in the source code provide with this post:

[php]
AIR_SDK=$USER_WORKSPACE/FlexSDKs/flex_sdk_4.0.0.14159_air2_android_prerelease

$AIR_SDK/bin/amxmlc -target-player 10.0.0 -debug=true DebugDemo.mxml[/php]

You’ll note that it’s using “amxmlc”, which is just a wrapper around mxmlc with configuration files pointed to include AIR libraries. Now we have a debug version of the SWF file, onto packaging a debug version of the apk.

[php]$AIR_SDK/bin/adt -package -target apk-debug -connect 192.168.1.100 -storetype pkcs12 -keystore $USER_WORKSPACE/renaun_air_cert.p12 -storepass password DebugDemo DebugDemo-app.xml DebugDemo.swf icon48.png icon72.png[/php]

The -target apk-debug -connect 192.168.1.102 are the critical parts. The -connect argument can take the form of a domain name, ip address, or “…”. The last options allows for you to set the IP address at runtime.

Compiling the Application and Getting it on the Android Device

Have your Android device set to USB debugging option on. Plug the Android device into the computer. Grab the Flash Builder 4 DebugDemo.fxp project code. Import project to Flash Builder 4 and make note of the project’s folder location. In the project files you’ll find a compile.sh file. Open a command line and navigate to the project’s folder location. Change the compile.sh’s permissions to allow for running it as a script (chmod 755 compile.sh will work). Open up the compile.sh file for editing and change the appropriate paths to your Flex/AIR SDK, Android SDK, connect ip address, and the location of your AIR signing certificate. After configuring your version of compile.sh correctly, change your directory location (cd src) into the src folder location and then do:

>../compile.sh

The extra code in the compile.sh that puts the apk file onto the device for you is the following:

[php]$ANDROID_SDK/tools/adb install -r DebugDemo.apk[/php]

You should be able to go onto your device and run the application. Force stop the application and then move on to the next steps to start the debug session in Flash Builder.

Starting a Flash Builder Debugger Session

First step is to configure the debug launch button to launch a debug session without loading the local SWF. In Flash Builder 4 with the DebugDemo project selected click on the Debug Launch icon’s side arrow and drop down to the “Other …” button. Here is the screenshot:

Since the project is an AIR project type there is some hacking to be done to make it launch the debugger without launching the AIR’s debugger adl. First select the “Web Application” drop down list, then right click and select the New icon, as seen in the picture below:

Now fill out the new launch configuration with the appropriate project name “DebugDemo” and “about:blank” in the “URL or path launch” options. It should look like this:

Now the debugger will be launched from this configuration and will not load any SWF’s because about:blank goes nowhere. This puts the Flash Builder 4′s debugger in a state of waiting for a connection on the debugger port, note it will time out after some time.

Note when launching you can go into the launch configuration page and launch it by selecting “DebugDemoDebuggerLaunch” and clicking on the Debug button. With this separate configuration item your AIR debugging will still work (if it wasn’t a AIR project type you could still make a separate configuration item to not conflict with the normal debugging). With two debugging configuration options for the same project Flash Builder 4 prompts the user to select which configuration option they want to run when clicking on the Debug icon. This looks something like this:

Go ahead and launch the new debug configuration item and it should ask to switch to the Flash Builder’s Debugger perspective. Switching to the debugger perspective shows the project waiting for a debug session connection.

With the AIR application on the device and the Flash Builder 4 waiting for the debug session launch the app on the device. When it connects it should look like this:

Now the application can be debugged with breakpoints and trace statements. Because the debug session was started inside the project with the same source code as the AIR application on the Android device it knows how to proceed like as if it was debugging locally. To see the debugging in action take a look at the video I made:

On Device Debugging AIR for Android with Flash Builder 4 from Renaun Erickson on Vimeo.