An alternative way of using sio2 iPhone SDK

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.

If anybody have trouble following the guide, just leave comments below. I will send out copies of the static lib project files

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).

---------- Update (15 Jan 2009) ------------
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!



---------- Update (18 Jan 2009) ------------
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.


---------- Update (23 Jan 2009) ------------
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.