Developing ‘Native Extensions for iOS’ requires knowledge of both native iOS code (C/C++/Objective C, XCode, static libraries etc) and AS3 code. So, it’s not unusual for developers to face issues. I have tried to list some of the most common roadblocks for native extension developers on this page.
An extension is recognized by its extensionID. Thus, one should try to keep it as unique as possible, as an application developer might want to use more than 1 native extension in his application. Having the same name will create conflicts and the application won’t get packaged or work as expected.
a. Same extensionID should be used in the extension.xml, application.xml and the AS3 Class where ExtensionContext.createExtensionContext() function is called.
b. Using “nativeExtension” as the extensionID isn’t really a good idea. Prefixing the extensionID with com.developerName is probably the way to go.
c. Prefix all the resources used by the extension with the extensionID. When multiple native extensions are used, the resources of all the extensions are merged in the application directory. Any conflicts can cause packaging/app run to fail. Since AIR 3.4, a new packaging option, -hideAneLibSymbols has been introduced, which allows to package and use multiple ANEs containing conflicting symbols. More information on this option can be found here.
2. SWC linking
The most common mistake made by application developers, while using native extensions in their app is to merge the SWC into application code.
a. While using Flash Builder , make sure that when specifying SWC linkage in the packaging options, for all the native extension SWCs, you have selected Link Type: “External” and not “Merged Into Code”:
b. While using command line to compile your application, make sure that the compiler switch used for linking SWCs is -external-library-path, and not -library-path and path to SWC is provided to this parameter. Another common mistake is to provide the ANE path here, instead of the SWC path.
c. In Flash Builder 4.6, there is in-built support for linking ANEs, and one can just directly go to the Native Extensions tab and specify the path to ANEs there. Flash Builder will take care of the linking.
a. For AIR 3.0 (native extensions for iOS not supported in AIR namespace <3.0), the extension descriptor namespace to use is 2.5, while for AIR 3.1, 3.2, 3.3, the extension namespace to use is 2.5/3.1. When using namespace 2.5, all the frameworks of iOS 5.1 SDK are linked by default. However, when using namespace 3.1, only these frameworks are linked by default:
While linking to any other framework/library, one needs to use the platformoptions flag of ADT while packaging an ANE, details of which are available here.
b. Make sure that the initializer and finalizer names in the extension descriptor map to actual function names being used in the native code. It is a good idea to prefix them with the extension ID.
4. Errors and Warnings
a. When packaging an app using native extensions, sometimes you may encounter errors and warnings similar to the following:
This is probably because the native extension is compiled with an iOS SDK greater than the one available in the AIR SDK. In this case, using -platformsdk <path to the latest iOS SDK> while packaging your application might resolve your issue.
b. Sometimes, you may encounter an error of the type:
This is probably because you have not included the extension in your application.xml. To fix it, add the extensionID of your applicationin your application descriptor.
c. You might get some linker warnings of the type:
You may safely ignore them.
d. Sometimes, it might so happen that when using Flash Builder, your IPA does not get compiled, however, there’s no real error you can see. It may be that the ld warnings take up the entire error screen and the actual errors are not visible. In that case, package the IPA using the ADT command-line to view the actual errors.
e. At times, an application using Native Extensions doesn’t get packaged in Flash Builder/ Flash Pro. This is because, when using native extensions, warnings are not suppressed, and packaging fails in Flash Pro/ Flash Builder, when the number of warnings is high. In this case, the solution is to use -w linker option in the platform.xml file in the ANE.
If that is not possible (it’s a precompiled ANE), you may use the ADT command line, instead of Flash Builder/Flash Pro to package the application. These issues are fixed in the latest Beta versions of Flash Builder 4.7 and Flash Pro CS7.
5. Exception Handling in native Code
Exception handling in the native iOS code (Objective C/C/C++) is supported since AIR 3.4. You can find more information on it here.
6. Debugging Native Extensions
You may find details of this here.
7. When and how to use Entitlements
Details can be found here.
8. Using platformsdk switch of ADT on Windows
With AIR 3.3, it is possible to package an IPA using the platformsdk switch on Windows too. You may find the details here.
9. Using release SWF in Flash Builder
Whenever creating IPA to submit to the Apple App Store, always use the release swf of the application. The release swf can be found by selecting Project>Export Release Build option of Flash Builder. The swf obtained by using Debug or Run option is the debug swf, which is much larger in size, as it contains debugging information.
Sample Native Extensions for reference can be found here.
10. dSYM file not getting generated on Mac OSX 10.8
The .dSYM file is generated for iOS apps using native extensions (in the same folder as the .ipa), when packaging on Mac. This file is helpful in debugging native code. However, on OSX 10.8, the
dsymutil tool used to create dSYM files has been moved out of
/usr/bin directory. It now resides in
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer or the path corresponding to your XCode installation. As a result, ADT and Flash Builder can no longer find it. So, to be able to use .dSYM files for debugging, either add the new path to your
PATH variable or create a symbolic link to
/usr/bin or simply copy the file to