iOS5 support for AIR/Using external SDKs to package apps

AIR 3.1 introduces significant improvements to the way native extensions can be used on iOS. Firstly, it lets you package your apps with an external SDK so that you are not restricted to using the captive SDK. If you have built an extension with the latest iOS SDK to access the latest features you can now specify that SDK when packaging the app. You can specify an iOS sdk to link with using the -platformsdk switch when packaging an IPA. Simply add -plaformsdk /path/to/iPhoneOS5.0.sdk to your regular commandline for packaging the ipa. The complete command line will look like this:

adt -package -target ipa-app-store -provisioning-profile ./myProfile.mobileprovision -storetype pkcs12 -keystore ./Certificates.p12 -storepass XXX myApp.ipa myApp-app.xml Main.swf -extdir ext/ -platformsdk /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.0.sdk/

 

The -platformsdk switch is supported both on Mac and on Windows. The packager will not attempt to validate the SDK being used to create the IPA. Any errors encountered when packaging the IPA will be reported back to you.

The packager, of course, does not know anything about the frameworks and the libraries available in the iOS SDK and you would have to specify any dependencies on them explicitly. This is where the second enhancement comes in: Starting AIR 3.1 you can specify dependencies on frameworks or shared libraries as well as other linker options when creating your ANE. The linker picks up these options when linking your extension to the runtime. The runtime links with the following frameworks for extension namespace version 3.1 by default:

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

If your extension uses any other frameworks or any shared library you will have to specify the dependency explicitly. If you specify an external SDK when packaging the IPA, the packager will look in the System/Library/Frameworks and the usr/lib subdirectories of the sdk for the frameworks and the shared libraries respectively by default. You can specify additional search directories in the descriptor file. These paths should be relative to the sdk root. If the captive sdk is used to package the IPA, the frameworks listed in the descriptor file will be picked from within the AIR SDK directory and the search paths specified in the file will be ignored. You will have to add these dependencies and any other linker options  to a platform specific descriptor file. The platform specific options file will have to be specified when packaging the ANE using the new -platformoptions switch. A options file might look like this:

<platform xmlns="http://ns.adobe.com/air/extension/3.1">
    <sdkVersion>5.0</sdkVersion>
    <linkerOptions>
	    <!-- to use the Twitter framework -->
        <option>-framework Twitter</option>
		<!-- to link with the libiconv.dylib -->
        <option>-liconv</option>
    </linkerOptions>
</platform>

And a command line to create an ANE with the platform options might look like this:

adt -package -target ane myextension.ane extension.xml -swc mySwc.swc -platform iPhone-ARM library.swf libmylib.a -platformoptions myplatformoptions.xml

 

Till AIR 3.0, you could only use frameworks which were shipped with the AIR SDK. As the packager did not provide the extension developer any way of specifying dependencies of the native code on other binaries, it linked in all available frameworks. Since the minimum supported version of the SDK for AIR 3.0 was 4.0, it only linked in frameworks available in iOS SDK version 4.0.  The runtime will maintain this behaviour for extension namespace version 2.5 to maintain backward compatibility.

Yet another enhancement is the facility to specify custom entitlements for your application. If your extension needs special entitlements to run you can specify those entitlements in the iPhone specific section of the application descriptor as follows:

<iPhone>
	<!-- A list of plist key/value pairs to be added to the application Info.plist -->
	<InfoAdditions>
            <![CDATA[
                ...
            ]]>
        </InfoAdditions>
        <!-- A list of plist key/value pairs to be added to the application entitlements -->
        <Entitlements>
            <![CDATA[
                <key>keychain-access-groups</key>
                <array>
                    <string>...</string>
                    ...
                </array>
                ...
            ]]>
        </Entitlements>
</iPhone>

To find out how to add custom entitlements to applications when using older versions of the AIR SDK see my older post.

Update: -platformsdk switch is now supported on Windows since AIR 3.5. When using the iOS SDK on Windows, be sure to extract it using a reliable DMG extractor tool which preserves symbolic links. Else you might encounter linker errors.

59 Responses to iOS5 support for AIR/Using external SDKs to package apps

  1. katopz says:

    would be nice if you provide some single zip working example for helloworld eg. call to AVFoundation and get some result back, fyi that i can build .a and ane properly+working but this stuff seem to be another door am i right? :)

  2. This means that if an extension needs a different framework other than the default build in ones, one needs a Mac to compile a final app. Don’t you think that Adobe should provide a way so that even PC useres will still be able to compile Air 3.1 apps with extensions for iOS?

    • rajorshi says:

      We should and we are working on it. Building an app using external SDK needs a completely different tool chain and porting that tool chain to Windows was not possible in the AIR 3.1 timeframe. ~rajorshi

  3. Hi rajorshi, sounds great! Thanks for the info.

  4. Maybe you’ll find my example helpful http://flashsimulations.com/2011/11/30/ios-native-extension-for-adobe-air-in-app-mail-composer/
    You can get get sources from github and check it out
    Piotr

  5. Pingback: iOS native extension for Adobe AIR. In-app mail composer | flashsimulations.com

  6. Keith Starling says:

    You say that “[y]ou can specify additional search directories in the descriptor file”, but I’m not seeing anything that says how to do that. I’ve got a custom framework that I’d like to compile against, but would prefer to not have to put it in the global SDK folder.

    • rajorshi says:

      To specify an additional search path add the following option: <option>-F/path/to/search/</option>
      ~rajorshi

      • Keith Starling says:

        Now it builds… but I get a segfault when running.

        • rajorshi says:

          Is the custom framework you linked to a static framework? If it is not, the application will not find it on the system and crash on load. iOS does not allow third-party frameworks to be installed on the device. What does the crash log say?

          • Keith Starling says:

            It’s a static framework, I’m using it successfully in an Obj-C project for iPad. The crash log is just saying:

            Exception Type: EXC_BAD_ACCESS (SIGSEGV)
            Exception Codes: KERN_INVALID_ADDRESS at 0x00000008

            in the main thread

          • rajorshi says:

            It’s hard to say from such a generic message. If you are convinced your code is not at fault and the problem is in the runtime please log a bug with Adobe.

            ~rajorshi

  7. nivedit says:

    rajorshi – Thanks for the helpful post.
    Can you elaborate more on the -F option for specifying a directory to search the library.
    Per the post above the path should be relative to sdk is this the AiR SDK you are referring to ??
    Please help…

    –nivedit

    • rajorshi says:

      The -F option is useful if you are using an external sdk with the -platformsdk option. The path should be relative to the iOS sdk root. If you are using the captive sdk, you will not need this switch. In general, these switches are passed on to the linker without any changes, so the best reference for them is the man page for the ld.

      ~rajorshi

      • nivedit says:

        rajorshi – i am using command line option adt on mac to create the ipa file.
        I have a third party library .a file that i want to integrate with, where do i need to place this on the mac. I do not specify any iOS sdk when creating the ipa.

        Please help.

        • rajorshi says:

          Place the static library (say, libmylib.a) in some directory and add the following options:
          <option>-L/full/path/to/directory</option>
          <option>-lmylib</option>

  8. Alex Yamane says:

    Dear Rajorshi,
    I have code to post on Twitter that works fine in Obj-C for iPhoneOS. When I try to add libxml2.dylib using the above example (i.e. -lxml2) to create an ipa file, I get an error that “ld: library not found for -lxml2”. I have tried (a) adding the -L/path/, (b) adding -F/searchdir/, (c) try adt command with and without -platformsdk flags, and (d) move the .dylib file into the /AIRSDK folder, but continually get this error. Do you have any suggestions on what I am doing wrong?

    thank you,
    ~alex

    • rajorshi says:

      You seem to be doing the right thing. Use the following platform options:

      <linkerOptions>
        <option>-L/usr/lib</option>
        <option>-lxml2</option>
      </linkerOptions>

      Also use the -platformsdk option when packaging the IPA.

      ~rajorshi

    • Bala says:

      hi Alex Yamane ,

      Is this problem solved ? I am also getting same kind of issues. Could you please share your views on this ?

  9. Michelle says:

    I’m trying to get ADT to link with libicucore.dylib, so –
    I’ve created platformoptions.xml:

    <platform xmlns=”http://ns.adobe.com/air/extension/3.1″>
    <sdkVersion>5.0</sdkVersion>
    <linkerOptions>
    <option>-licucore</option>
    </linkerOptions>
    </platform>

    And added:
    -platformoptions platformoptions.xml to my ane build script

    ../../../AdobeAIRSDK/bin/adt -package -target ane BFGlibNativeExtension.ane extension.xml -swc BFGlibNativeExtension.swc -platform iPhone-ARM library.swf libBFGlibNativeExtension.a -platformoptions platformoptions.xml

    I also added the following to the command line when packaging the SDK:
    -platformsdk /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.0.sdk/

    But I’m still getting
    Undefined symbols:
    “_u_strlen”, referenced from:
    For everything that should be defined in libicucore.dylib

    Any advice?

    [rajorshi] EDIT: combined multiple comments into one with proper formatting

    • rajorshi says:

      Hi Michelle,
      You seem to be doing everything right. This is most likely caused by some rogue setting in your project files. Can you share your project files so that I can have a look? I noticed that you are talking to Neha on the forums. You can share your files with her and we will look at them.

      ~rajorshi

  10. Bala says:

    Excellent post ! Was so helpful in many ways.Thanks a lot !

  11. Bala says:

    hi rajoshri,

    -licucore
    -L/myfolder/thir party lib files

    I am trying to add 2 extern files, one is libicucore.dylib and other is my .a fle

    is my code above is correct ? My question is when i set the search path , did it searches the libicucore.dylib inside my search path ? or No ?

    • rajorshi says:

      Which is the other .a file you are referring to? If it is the native extension library, then it has to be specified in the commandline and will be picked up automatically by the packager. libicucore.dylib is in the /usr/lib directory so what do you have in /myfolder/thirdparty?

      ~rajorshi

  12. Pingback: Adobe Native Extension for iOS Game Center – Part 1 « David Flatley

  13. Bala says:

    hi,

    I have 3 third party .a files , libclientrt.a , libMO.a,libSupObj.a (files which links my application with sup).

    I need to package these files along with the and creation.

  14. Bala says:

    this is the code i used….is this correct ?

    -framework Foundation
    -framework CoreFoundation
    -framework AddressBook
    -framework QuartzCore
    -framework Security
    -lstdc++
    -lz.1.2.5
    -licucore.A
    -L/Developer/Library/SUP/ObjectiveC/libs/Debug-iphoneos
    -lclientrt
    -lMO
    -lSUPObj.a
    -lthirdparty
    -L/searhPath/for/thirdlibrary

  15. Bala says:

    hi rajorshi,

    After creating and file with the above code, i included the and file in flash builder project under extensions.But while creating ipa file , i am getting the following error. Any idea ?


    Error occurred while packaging the application:

    ld: library not found for -lstdc++
    Compilation failed while executing : ld64″

  16. Bala says:

    Kindly ignore my above post

    After creating ane file with the above code, i included the ane file in flash builder project under extensions.But while creating ipa file , i am getting the following error. Any idea ?


    Error occurred while packaging the application:

    ld: library not found for -lstdc++
    Compilation failed while executing : ld64″

  17. Bala says:

    hi rajoshri,

    I had solved the above issue by pointing the iOS sdk location in the flash builder.

    But now i am getting the same error on my third party file

    This is the error i got

    “Error occurred while packaging the application:

    ld: library not found for -lSUPObj.a
    Compilation failed while executing : ld64”

    In the search path i mentioned, is correct. Search path has this file. Any idea ?

  18. Bala says:

    hi rajoshri,

    Thanks for the forum. i solved the above problem. It seems i had included -SUPObj.a in platform options xml file.

    i just removed .a (end of -lSUPObj) which worked.

    • Jason says:

      Hi rajorshi:

      I’m trying to get ADT to link with libz.1.2.5.dylib and some third parties libraries which are hosted in folder “/Users/zgzong/Work/air_workspace/AM_compilation/NativeIOS/libs”, so I’ve created platformoptions.xml:


      <platform xmlns="http://ns.adobe.com/air/extension/3.1">
      <sdkVersion>5.1</sdkVersion>
      <linkerOptions>
      <option>-framework MessageUI</option>
      <option>-framework CoreAudio</option>
      <option>-framework AudioToolbox</option>
      <option>-framework AVFoundation</option>
      <option>-framework Foundation</option>
      <option>-framework SystemConfiguration</option>
      <option>-framework UIKit</option>
      <option>-L/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.1.sdk/usr/lib</option>
      <option>-libz</option>
      <option>-F/Users/zgzong/Work/air_workspace/AM_compilation/NativeIOS/libs</option>
      <option>-libcrypto</option>
      <option>-libcurl</option>
      <option>-libcrypt</option>
      <option>-libpg-error</option>
      <option>-libmfcbroem_ios</option>
      <option>-libssh2</option>
      <option>-libssl</option>
      </linkerOptions>
      </platform>

      And added:
      -platformoptions platformoptions.xml to my ane build script

      ../../../AdobeAIRSDK/bin/adt -package -target ane AMANE.ane extension.xml -swc AMLibrary.swc -platform iPhone-ARM -C “${native_ios_directory}” . -platformoptions platformoptions.xml

      I also added the following to the command line when packaging the SDK:
      -platformsdk /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.0.sdk/
      but I keep get the following error.
      [exec] ld: library not found for -libz.1.2.5
      [exec] Compilation failed while executing : ld64

      I have tried (a) adding the -L/full path/, (b) adding the -L/relative path, such as “-L/usr/lib” (c) adding -F/searchdir/, (d) try adt command with and without -platformsdk flags, and (e) move the .dylib file into the /AIRSDK folder, but continually get the above error.

      And also if I remove the linker options for libz.1.2.5.dylib. I will get the following error

      [exec] ld: library not found for -libcrypto
      [exec] Compilation failed while executing : ld64

      Do you have any suggestions on what I am doing wrong?

      • rajorshi says:

        The library options should look like this:

        <option>-lz</option>
        <option>-lcrypto</option>
        <option>-lcurl</option>
        <option>-lcrypt</option>
        <option>-lpg-error</option>
        <option>-lmfcbroem_ios</option>
        <option>-lssh2</option>
        <option>-lssl</option>

        The linker will add a lib and a .a to the name you supply to get the complete library name. So, on specifying -lX, the linker looks for library libX.a.

        ~rajorshi

        • Jason says:

          Thank you very much, that does work. However when I package my app on command line, i got the following warnings. Any hints, please?

          [exec] ld: warning: ARM function not 4-byte aligned: _IDctSlow_ARM from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(idct_part.o)
          [exec] ld: warning: ARM function not 4-byte aligned: IDctSlowProcessRowLoop from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(idct_part.o)
          [exec] ld: warning: ARM function not 4-byte aligned: IDctSlowSkipArithmeticInRow from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(idct_part.o)
          [exec] ld: warning: ARM function not 4-byte aligned: IDctSlowProcessColumnLoop from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(idct_part.o)
          ...
          ...
          [exec] ld: warning: ARM function not 4-byte aligned: Copy12x12_CSrcAlign1 from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(copy12x12.o)
          [exec] ld: warning: ARM function not 4-byte aligned: Copy12x12_CSrcAlign2 from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(copy12x12.o)
          [exec] ld: warning: ARM function not 4-byte aligned: Copy12x12_CSrcAlign3 from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(copy12x12.o)
          [exec] ld: warning: ARM function not 4-byte aligned: _tDecodeBool from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(tDecodeBool.o)
          [exec] ld: warning: ARM function not 4-byte aligned: _tDecodeBool128 from /Applications/Adobe/Adobe Flash Builder 4.6/sdks/4.6.0/lib/aot/lib/libRuntimeInterpreter.arm-air.a(tDecodeBool.o)

          • rajorshi says:

            These warnings are expected because you are linking with an external SDK which is different from the one used to compile the runtime. It is safe to ignore them.

            ~rajorshi

  19. Pingback: 20 tips for creating Air Native Extensions for iOS | Hire Flash Developers

  20. Kathe Allred says:

    I take pleasure in, lead to I found just what I was looking for. You have ended my 4 day long hunt! God Bless you man. Have a nice day. Bye

  21. Pingback: Using the iPad retina display with Adobe Air

  22. Thenrion says:

    Hi, thank you for this page.

    Namespace of platform.xml should match extension namespace.

    Do you know something about this ? I follow the complete example but ADT return this error and does not package the ane file.

    Thank you

    • rajorshi says:

      It means what it says. The namespace of the XML file you specify as platformoptions should be the same as the namespace of the extension xml.

      ~rajorshi

      • Thenrion says:

        Thank you for your feedback.

        I didn’t understand at first because the error description compared a platform.xml file with an “unknown” extension. I know this is tricky but while fighting with ane for the first time, “extension” ( without .xml ) could be understand as many things.

        But it works perfectly ! Thanks

  23. Pingback: 给iOS开发AIR Native 扩展的20条建议 - 博客 - 伯乐在线

  24. Karl-Gustav says:

    Thanks for this hint – now the new ipad3 is out … and I am developping apps with Flash CS 5.5 on Windows … any idea when Adobe will support the ipad3 with Flash CS 5.5? I bought this tool because of its really great ipad-packager and now I am stuck waiting for an update … and my app-users are waiting as well.
    Thanks for your feedback and thanks as well for your excellent work with the Flash-platform!

  25. Pingback: 20条开发AIR Native Extension的建议 | Flash开发者大会

  26. rahuls says:

    Hi,

    In my case I am using two extensions, native email + flurry. but when i compile at my terminal with platform sdk set to ios5. i get error and ipa is not generated. Also I have set the library to point to the swcs as external.
    please help

    ld: warning: -dead_strip with lazy loaded static (library) archives has resulted in a duplicate symbol. You can change your source code to rename symbols to avoid the collision. This will be an error in a future linker.
    ld: warning: duplicate symbol _ContextInitializer originally in /var/folders/B3/B3cOnAGjEUeCwYcivTB9EU+++TI/-Tmp-/c0e634de-5131-4f88-af85-289375e39b39/libpl.randori.air.nativeextensions.ios.MailExtension.a(MailExtension.o) now lazily loaded from /var/folders/B3/B3cOnAGjEUeCwYcivTB9EU+++TI/-Tmp-/c0e634de-5131-4f88-af85-289375e39b39/libcom.sticksports.nativeExtensions.Flurry.a(FlurryIosExtension.o)

  27. Pingback: Building a Native Extension Part 3 – The iOS Code | Digital Primates

  28. sonicoliver says:

    Where do I put the “command line” when using Flash Pro? :(

  29. Pulkit Gupta says:

    Dear Rajorshi,

    I got started with native extensions after your session at B’lore. Your posts have all been extremely useful. I need your help once again.

    I am working on an iOS native extension for Camera. I am making use Of ALAssetLibrary framework to write images to gallery, get the URL and load again using the same framework.

    I am able to save image to the gallery successfully, but anytime after invoking the camera, I call FREDispatchStatusEventAsync event, the app crashes. After a lot of research I could not get around this issue. Finally I decided to call an ObjC function from Flex at an interval to check the status. This works fine and I get the updated status in Flex, but after the status update, If I try and dispatch an AS3 event to inform listeners, the app crashes again.

    Can you please throw some light on this?. I can share the code with you if you’d like to have a look.

    • rajorshi says:

      Hi Pulkit,
      It’s great to know that my posts have been of help to you. If you are still facing this issue please feel free to start a thread discussing it on our forums. Someone from the team will look at it. We will need much more information to get to the bottom of it and it’s hard to track issues in the comments section!

      ~rajorshi

  30. Pingback: The Unofficial Guide to the New iPad 3 Retina Display and Adobe AIR

  31. Pingback: 20条开发AIR Native Extension的建议-开心快乐每一天-梦想小熊小爱

  32. Carl says:

    Using Applescript to call the adt command, Error about Copy Cloner make any sense?

    tell current application
    do shell script “/Users/Carl/Projects/source/AirExtentions/AdobeAIRSDK_MAC/bin/adt -package -target ipa-test-interpreter -storetype pkcs12 -keystore /Users/Carl/Projects/source/AirExtentions/Vuforia/Vuforia/cert/CarlDev.p12 -storepass 1234 -provisioning-profile /Users/Carl/Projects/source/AirExtentions/Vuforia/Vuforia/cert/iOS_Team_Provisioning_Profile_.mobileprovision /Users/Carl/Projects/source/AirExtentions/Vuforia/Vuforia/dist/Vuforia-debug-interpreter.ipa /Users/Carl/Projects/source/AirExtentions/Vuforia/Vuforia/application.xml . -C bin . -C ‘icons/ios’ . -extdir /Users/Carl/Projects/source/AirExtentions/Vuforia/Vuforia/ext/ -platformsdk /Users/Carl/Projects/source/AirExtentions/Vuforia/iPhoneOS5.1.sdk”
    –> error “/Applications/Carbon Copy Cloner.app/Contents/CodeResources is not part of a Mac OS X Native Extensions framework

  33. Pingback: ANE使用流程和问题解决 - 咕噜喵和兔子的下午茶

  34. Jeremy Hicks says:

    If I have compiled an XCode library that includes the 3rd party framework, do I need to also include it in the -platformoptions file?

    Here’s ANE Command (if I run it with platform options pointing to this external framework, the result is the same):
    adt -package -target ane KiipNativeExtension.ane extension.xml -swc KiipNativeExtension.swc -platform iPhone-ARM -C ios . -platform default -C default .

    — that works fine, no apparent errors

    Then I will publish the .swf from Flash Pro CS6

    When I run:
    adt -package -target ipa-test-interpreter -storetype pkcs12 -keystore Certificates.p12 -storepass passwd -provisioning-profile Distribution_Ad_Hoc.mobileprovision TestKiip.ipa TestKiip-app.xml TestKiip.swf -extdir .

    I will get the following error :
    ld: warning: -ios_version_min not specificed, assuming 4.0
    ld: duplicate symbol _OBJC_CLASS_$_FIXCATEGORYBUGKP_ASIHTTPRequest in /var/folders/2g/4jk4pqbs28v13vh9scbj1cq40000gn/T/584875fa-8df2-4b42-986b-ed6365a1aeb2/libcom.slaphostgames.extensions.KiipNativeExtension.a(KP_ASIHTTPRequest+OAuth.o) and /var/folders/2g/4jk4pqbs28v13vh9scbj1cq40000gn/T/584875fa-8df2-4b42-986b-ed6365a1aeb2/libcom.slaphostgames.extensions.KiipNativeExtension.a(KP_ASIHTTPRequest+OAuth.o) for architecture armv7
    Compilation failed while executing : ld64

    Any thoughts?

  35. Pingback: 使用Adobe Air技术开发ipad视网膜技术(new ipad) : 守望者3D智库