iPhone & Unity3D: Integrating 3rd Party Static Libraries in Unity3D Generated XCode Projects

Deploying for iPhone from Unity3D can be a little bit tricky, especially when customised code or 3rd party libraries are part of the project. So I decided to publish my own little check list and some hopefully useful information. In general I recommend the newest Unity3D version you can get (3.4 at time of writing) because there were some problems in Unity3D 3.3 leading to a bunch of errors and warnings.

• Start
• First Steps in XCode
• Integrating The Library Files in XCode
• Adjusting The Code in AppController.mm
• Finished

Start

My environment for getting the app up and running:

• Unity3D 3.4
• XCode 4.02
• iOS 4.3.3
• Some 3rd Party static library. In my case it is libm3SysLib.a and its header file m3SysLib.h. Put your library and header file at the places mentioning m3SysLib
• target iOS version 4.3
• target device iPhone 4 / iPod Touch 4th generation

First of all you have to check your build settings (File / Build Settings, button Player Settings):

Before 3.4 the target platform for armv7 was called “armv7 iPad only” which is pretty confusing as iPhone 4 was supported very well. SDK Version should be “iOS latest” to avoid manual configuration after XCode updates.

Pressing “Build And Run” pops  up a file chooser dialog for selecting output folder where to generate all XCode related stuff. Note that on subsequent builds to the same folder, Unity3D asks you if the generation should replace or append. Because we are going to make a couple of changes in the project file you should always press “Replace” later on, otherwise you have to repeat all your steps. Like always: backups are a pretty good thing 😉

First Steps in XCode

Now in XCode we have to check the project settings first:

We use armv7 architecture only because of the static library to include. If you need to run your app in simulator you have to provide an i386 version of your lib as well. Thus configuration gets far more complicated. Note the “Latest iOS” entry which should be set automatically by Unity3D. If not, set it manually.

OK, let’s try our very first CMD+B (build) without the library. I have got two warnings (Semantic Issues regarding kScreenOrientation and an incompatible pointer type UIViewEAGLView) that can be ignored. If your build fails or if XCode hangs during the last build phase, check the scheme (Product / Edit Scheme…). Sometimes the simulator is set as target by default after the very first Unity3D export, but we want to deploy the app on our iPhone:

Integrating The Library Files in XCode

Before we use a 3rd party library in XCode we need to

• Tell XCode where to find library
• Specify the location of the header files
• Optionally include a DefaultSettings.bundle

The library file must be linked to the app in XCode. This is done in project settings. Just select “Unity-iPhone” in the “Targets” section at the left and go to the “Build Phases” tab. The last expandable row shows the libraries to link with and new libraries can be added by clicking the “+” sign and choosing “Add Other…”. Note that your library might depend on some frameworks in my case for example CoreMotion.framework. These have to be added as well. After adding the library file itsef (in my case libm3SysLib.a) from file system and dependent frameworks you should have something similar to:

Header file including takes place in the “Build Settings” tab of the project. Just add the location in “User Header Search Paths”. Hint: Use the search field to filter:

If your library relies on a default settings bundle, just copy it from wherever it is supplied to the project root.

Adjusting The Code in AppController.mm

In order to handle app life cycle properly we need to edit some code in AppController which is the UIApplicationDelegate of our app. Following places will typically need to be adjusted:

• Header file include section, take your header file instead of m3SysLib.h:
  #import “m3SysLib.h”
• – (void) registerAccelerometer
  If you don’t need it or like in my case use more sophisticated sensor handling, type return; in the first line to avoid unnecessary sensor usage.
• – (void) Repaint
  I commented out the whole if block if (kAccelerometerFrequency > 1e-6 … for the same reason
• – (void) applicationDidFinishLaunching:(UIApplication*)application
  Here we do our library initialisation stuff
• – (void) applicationDidBecomeActive:(UIApplication*)application
  Called every time the app becomes active
• – (void) applicationWillResignActive:(UIApplication*)application
  Called every time the app becomes inactive i.e. goes to background
• – (void) applicationWillTerminate:(UIApplication*)application
  Optionally for old iPhone 3 systems that do not support multi-tasking
• Other events you want to react on

Finished

We are hopefully done and everything is up and running. Using our library from inside Unity3D would go beyond scope of this blog entry. I recommend Clever Martian’s Blog – An Experiment with iPhone Native UI and Unity 3 Pro. It helped me a lot and his downloadable example project was easy to set up.

If you liked this posting don’t hesitate to push the Like, +1 or Twitter button, or you may leave a comment below (no registration required).