First we must thank the author of sio2 iPhone sdk, who have done a
great deal of work to make our life easier. And better yet, it’s free.
If you are looking for a free iPhone game sdk, please find out more
details on http://www.sio2interactive.com. Anyway, if you’ve reached this blog post, you probably already know of this sdk. 

Now,
we talk about the issues. It is very powerful and all that, the big
issue I have is that the way of using the SDK is pretty primitive. I
need to customize based on the template project, which i don’t like
because it take time to renamed the stuff.
Now if I don’t want to
follow that approach, I basically have to include all the source files
in my project and compile very thing. That is not too bad, until I had
to do clean-build frequently. A clean-build (clean first and then
build) takes almost a minute on my 20 inch iMac, which is very counter
productive.

My solution to this is to create a Cocoa Static
Library project out of the sdk source, and reference that static
library in my own game project.
Here is a step-by-step guide on how to do so:

  1. Create
    a Cocoa Static Library project in Xcode. Xcode -> File -> New
    Project -> Static Library -> Cocoa Static Library, named sio2.
  2. Download sio2 sdk, extract it. In the folder SIO2_SDK_v1.3.1, locate ‘src’ folder.
  3. In Finder, copy that src (or move if you wish) into the project folder ‘sio2’
  4. In Xcode, add the ‘src’ folder to the newly created project. To do so:
    1. Ctrl
      click on the project root, Add -> Existing Files -> Select the
      ‘src’ folder (note that this is the one in the sio2 folder)
    2. In the confirmation dialog, make sure ‘copy items to destination folder’ is UNCHECKED
  5. If you try to compile now, you get a few thousand errors, there are a few things you need to do in order make it compile
    1. In
      Xcode, delete a file named ‘sio2_wrap.c’ from the ‘lua’ group. Since I
      don’t know whether this file is going to be useful in the future or
      not, just choose ‘Delete References’ when Xcode asks.
    2. Now,
      select the sio2 group, you will see a bunch of files named like
      ‘sio2_xxxxx.h’ or ‘sio2_xxxxx.cc’. You need to select all of them
      (except README.txt) in the top-right view, hit the Get Info icon in the
      tool bar. In the General tab, change the file type to
      ‘sourcecode.cpp.objcpp’.
    3. In Other Resources, open sio2_Prefix.pch. Replace ‘#import <Cocoa/Cocoa.h>’ with ‘#import <Foundation/Foundation.h>’
  6. Now build. You get no error but a tiny warning. I assume that is not critical.
  7. Change
    the configurations, make sure you build for all the following 4
    combinations. (if you are targeting 2.1, change version number from 2.0
    to 2.1 accordingly).

    1. Device – 2.0 | Debug
    2. Device – 2.0 | Release
    3. Simulator – 2.0 | Debug
    4. Simulator – 2.0 | Release
  8. In Xcode, open your own game project
  9. Ctrl
    click on game project root, Add -> Existing Files, choose the
    sio2.xcodeproj we’ve just created. In the confirmation dialog, make
    sure ‘copy items to destination folder’ is UNCHECKED
  10. Once
    added, you will see a file name ‘libsio2.a’ under sio2.xcodeproj. Drag
    that file to Targets -> game_name -> Link Binary With Binaries.

    1. Remember we have built 4 version of the static library?
    2. Xcode is smart enough to know which one to link to, when you change the configuration in your own game project.
  11. Now
    you need to include a single header file ‘sio2.h’. You can locate the
    header file by either add header search path to your project
    configuration, OR you may just place the sio2 project folder in
    parallel with your game folder and use a relative path like this:
    #import “../../sio2/src/sio2/sio2.h”
  12. You are now good to go. Enjoy the power of sio2 sdk.

So what do you gain from this approach?

  • Faster building time
  • Cleaner project structure
  • Reusability, use the same static library for multiple game projects is not an issue at all.
  • You don’t have to build a project from the ‘tempate’ project, which is kinda old-school. You get to name your project properly.
  • If
    the sdk is updated, just replace the ‘src’ folder in your sio2 static
    libary project. And then build for the 4 configurations. You don’t have
    to do anything to all your game projects referencing this static
    library (except for compatabilty check of couse).

Make
sue you select ‘Cocoa Static Library’ while creating the sio2 project.
If ‘Cocoa Dynamic Library’ is choosen instead, you will get over 2000
compilation errors. That’s because we have not link all the frameworks
yet. I don’t see the point of using a dynamic library yet, so stick to
the static way. cheers!

There are some concerns from sio2 forum about the loss of debug symbols. The answer is debug symbols are not lost.

You
will still be able to step into all the sio2 functions and view the
value of primitives and structure without any issue. This works for
both simulator and device, as long as build config of your game project
is set to Debug. Because by doing that, Xcode links the Debug sio2
static library which contains all the necessary debug symbols.

With
all that said, it WILL be a bit troublesome if you need to actually
modify sio2 static library itself (because you need to open up the sio2
static library project, do some modification and build for all 4
configs).

So i’d say that this way is better for game developers who are using sio2 sdk, but definitely not for sio2 developers.

For
developers who wish to frequently update the sio2 SDK to suit their
needs. Remove the group “sio2” (the directly contains all the files
start with ‘sio2_’) from the static lib project, and added it into your
game project. Of course the file type must be changed to
sourcecode.cpp.objcpp, before everything compiles.