Commonly faced issues while developing Native Extensions for iOS

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.

1. extensionID

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.

3. extension.xml

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:

  • CoreFoundation
  • UIKit
  • MobileCoreServices
  • CoreGraphics
  • SystemConfiguration
  • AudioToolbox
  • CFNetwork
  • QuartzCore
  • CoreLocation
  • CoreMedia
  • CoreVideo
  • AVFoundation
  • Foundation
  • OpenGLES
  • Security

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:

ld warning: unexpected srelocation type 9
ld warning: unexpected srelocation type 9
... (repeating several times)
Undefined symbols:
"_vDSP_vsdiv", referenced from: ...
 ld: symbol(s) not found
Compilation failed while executing : ld64

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:

Exception in thread "main" java.lang.Error: Unable to find named traits:
Compilation failed while executing : ADT

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:

ld: warning: ARM function not 4-byte aligned

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/ 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 dsymutil at /usr/bin or simply copy the file to /usr/bin folder.

7 Responses to Commonly faced issues while developing Native Extensions for iOS

  1. I Look forward to iOS6 ANE, such AIR extensions for BookPass and now Apple’s iOS native maps will be needed… Even selling such ANE would not be a far fetched idea, I am not good at developing ANEs but would certainly hope developers out there who have such knowledge in the iOS SDK and AS3 to monetize on these ANE.

    I would certainly be a buyer.

  2. John says:

    my problem is

    VerifyError: Error #1014: Class could not be found.

    im trying to create a simple extension to get a UIView from iOs to As3.

    im packaging the ane with the adt tool.

    • neha says:

      Seems like that you have not linked the ANE using external linkage. If you are using command line mxmlc to package you swf, be sure to specify the swc using -external-library-path instead of -library-path. If you are using Flash Builder 4.6, select the native extensions tab in the project properties and add the ANE there. If you are using Flash Pro, link the ANE using the native extensions option.
      If you are using FB 4.5, link to the ANE’s swc file and select use external linkage instead of merge into swf.
      I guess this should solve your problem.

  3. Pingback: Flashache

  4. Pingback: AIR Native Extensions Collection

  5. Samuel says:

    I’m having a really weird problem today building an ANE for iOS. Or to be precise, an IPA of an application which uses an ANE. The native code of the ANE is frozen to an old version.

    I’ve tried to clean everything (remove the native libs, the ane file, the ipa, swfs, basically everything but source), rebuild everything, and still the old code. I can tell because it displays a message that isn’t in the new native code version.

    I’ve also tried to open the .a native library with an hex editor. I can’t find the sentence that is displayed, as it should be, because it doesn’t exist anymore in this new version. I’ve built the ANE, dezipped it, and checked the native library file inside of it the same way, it’s the good one. Then I’ve build an IPE using this very same ANE, from Flash Builder and from command line (just to be sure), and it still contains the old native library. I’ve tried to unzip the IPA to analyze the binary blob which contains my app and the extensions, and… The message that shouldn’t be here is here. Even if there’s no reference to it anywhere before building the IPA.

    Is there some cache, or something, anywhere on my Mac OS X computer, which I need to clean to fix this issue ? This is really problematic.

    Thanks for your answer.