How to debug your Android ANE

Unlike AIR native extensions for iOS, where you can debug either the native code or the ActionScript code, on Android you have the option to debug all of your code at the same time. This post shows you how to debug your Android ANE on a device via USB both in Flash Builder/Flash Pro and in Eclipse.

Here is a summary of the steps, click on each one for details:

1. Enable USB debugging on your device
2. (Windows only) Enable USB debugging on your machine
3. Make sure Eclipse can see your device
4. Prepare your AIR app for debugging
5. Create a dummy Eclipse project for your app
6. Replicate project settings
7. Run your app on the device
8. Hook the Eclipse debugger to your app and start debugging
9. What if you don’t have the native extension’s code?

1. Enable USB debugging on your device

On your Android phone or tablet open the development settings:

• Android 3.2 or older: Settings > Applications > Development;
• Android 4.0 to 4.1: Settings > Developer Options;
• Android 4.2 and newer: to make Developer Options appear under Settings, go to Settings > About phone and tap Build number seven times. God help you if you have my dyslexia and dyscalculia…

Select USB debugging.

2. (Windows only) Enable USB debugging on your machine

If you are using Windows, you will need to install a USB driver, in order to connect to your Android device. Android’s developer documentation has detailed instructions for that: http://developer.android.com/tools/extras/oem-usb.html

3. Make sure Eclipse can see your device

Connect the Android device to your machine via USB and check the Devices window in Eclipse (Window > Show View > Other > Android > Devices). Your device should be shown as Online:

If you can’t see your device in the list or it shows as Offline, try reconnecting the USB cable, restarting the device and/or Eclipse. If that’s any consolation, Flash Builder is even worse and requires a rain dance in addition to all of the above.

4. Prepare your AIR app for debugging

In your AIR app descriptor file (typically called YourAppName-app.xml and located in the src/ folder of your AIR project) enable debugging for Android. This requires adding the INTERNET permission and setting the debuggable attribute to true in the <manifest> entry inside the <android> section of the app descriptor:

<manifest android:installLocation=”auto”>
<application android:debuggable=”true”/>
<uses-permission android:name=“android.permission.INTERNET”/>
<!– other permissions and Android settings –>
</manifest>

1.2. Next, make a note of your app id in the <id> tag of the descriptor, for example:

<id>com.diadraw.CameraTestApp</id>

5. Create a dummy Eclipse project for your app

In Eclipse select File > New Project, then in the wizard select Android Application Project:

Set Application Name and Project Name to be the same as your AIR project’s. Set Package Name  to be the same as the app ID you had in your AIR app descriptor and prepend air. to that (Adobe AIR sneakily prepends that to your package when it’s installed on the device):

Uncheck Create activity: this project will contain no source code.

Leave the settings in the next couple of steps as they are and click Finish to create the project.

6. Replicate project settings

Your Eclipse project should have the same settings and permissions as your AIR application. In Eclipse open AndroidManifest.xml and make sure you set the same things as in the <android> section of your AIR app descriptor.

Tip: When you open AndroidManifest.xml in Eclipse, the file has several tabs at the bottom: Manifest, Application, Permissions and Instrumentation offer you a safe way of editing the file by filling in fields. The last tab, AndroidManifest.xml lets you edit the XML by hand. Take your pick.

7. Run your app on the device

If you are only interested in debugging the native Android side of your project, all you have to do is install the app and run it on the device.

To debug both the ActionScript and the native side at the same time, run your AIR project through the Flash Pro or Flash Builder debugger.

Tip: Flash Builder can be stroppy and refuse to see your device. First, check to see if your Android phone or tablet is supported by Flash and Adobe AIR: http://solutionpartners.adobe.com/flashplatform/certified_devices. If it’s in the list and you get this error message: Flash Builder could not find a connected device,

 make sure you connect your device via USB after you have started Flash Builder. Sometimes that rain dance comes handy too.

8. Hook the Eclipse debugger to your app and start debugging

You should now see your app listed as running in the Devices tab in Eclipse. Select the app process and click Debug the selected process (the green bug icon).

If you have the code for your Android ANE, you can put breakpoints in it and start debugging.

At this point, if you have started your app through one of the Flash debuggers, you’ll hit the breakpoints in your ActionScript code too.

9. What if you don’t have the native extension’s code?

You can still get useful information out of Eclipse’s debugger, such as crash or message logs.

To have a look at the information logged about the running of your app, open LogCat (Window > Show View > Other > Android > LogCat). This is where information is logged about all of the running processes on the device. You can limit the log to show you only messages coming from your app by creating a LogCat filter. Click the green plus sign to do that:

and in the Filter Settings dialog create a filter by Application Name, giving it the name of your app:

Another useful thing is the ability to take a screenshot of your device through Eclipse. To do that, click on the camera icon on the Devices tab: