Building a native extension for iOS and Android – Part 5: Building the ANE file

In earlier tutorials in this series, you created the main and default ActionScript libraries, the iOS library, and the Android library for a native extension. Now that all of the supporting projects have been built, it's time to put it all together. For native extensions, that means building an ANE file using the ADT tool.

Because Flash Builder does not yet support building ANE files, you must use the command line ADT tool, which is packaged with the AIR SDK. The ADT tool is located in AIR_SDK_DIR/bin.

1. Follow the steps below to build your ANE file:
2. Put all of the files into a folder using the structure below:

Note: The library.swf file is inside of the SWC file that the ActionScript project generates. Simply extract the contents of the SWC as if it was a ZIP file and you'll see the library.swf file.

2. Navigate to the build directory you've created. On OS X use the Terminal and on Windows use the command prompt. Run the following command:

In the command above, –C directory . indicates that all of the files in directory should be included in the ANE file. In contrast, –C directory library.swf would include only the file directory/library.swf in the ANE file.

Signing the native extension is optional. If you don't sign it Flash Builder will probably complain about it, but everything will still work as expected. To sign the ANE file, use any p12 certificate you have. If you don't have one, you can generate one from Flash Builder. Then, add these parameters to the command above:

If you're not supporting both iOS and Android, be sure to exclude the platform that you aren't supporting. You want the platforms used here to mirror the ones defined in the extension.xml.

Note: If you're having trouble running ADT, see Building Adobe AIR Applications—Path environment variables. If you get an error indicating "invalid extension.xml" there's a chance the extension.xml file can't be found. Be sure you are running the command from the build directory.

Follow these steps to include the ANE file in your project:

1. Go to the properties of your project in Flash Builder.
2. Select Flex Build Path and click the Native Extensions tab.
3. Click Add ANE and navigate to the ANE file you built.
4. At some point, either during this step or one of the following steps, Flash Builder should indicate that the package of the ANE must be included in the app descriptor file and that Flash Builder will automatically include it. Click Yes to this prompt.
5. Now that your native extension has been added, you must toggle it on for each platform you are supporting. In the Properties dialog box, select and expand Flex Build Packaging.
6. If you are supporting iOS, select Apple iOS and click the Native Extensions tab. Be sure that the checkbox in the Package column of your native extension is checked. Also be sure to specify the path to the iOS SDK (as mentioned previously) as the Apple iOS SDK setting. Click Apply.
7. If you are supporting Android, select Google Android and click the Native Extensions tab. Be sure that the checkbox in the Package column of your native extension is checked. Click Apply.
8. Click OK and choose Project > Clean to clean your project. You're ready to implement the native extension now!

If you make any changes that require you to rebuild the ANE file, I recommend removing the native extension from the Flex Build Path > Native Extensions tab and repeating the steps above to re-add the ANE file to your project. I've had some caching issues that caused an old version of the extension to be used if I didn't totally remove it and start the add process over from the start.

If you make changes to any of the libraries, be sure to update the files in the build directory. It's especially easy to overlook extracting the library.swf file from the main ActionScript library's SWC file. Also be sure to place this library.swf file in both the iOS and Android directories.

It's not difficult to automate this process via ANT. I don't cover it here, but many projects use ANT to perform the entire packaging process. You can even extract the library.swf file from the SWC file using ANT.

Many steps are involved in creating a native extension for Adobe AIR, but following the steps in this tutorial series will help you avoid overlooking some of the finer details that are required to get it all working. You can find great examples of native extensions on the Adobe AIR Developer Center. I encourage you to check them out to get an even better understanding of what native extensions can do.