Adding SIO2 to an Existing Xcode iOS Project

Updated (2011/01/16) – Please note that this article covers SIO2 v1.4, which was the original free/low-cost version of SIO2. This article does not cover SIO2 v2.x.

SIO2 is an interesting and useful library for building 3D OpenGL ES applications under Apple’s iOS. While not strictly object-oriented like Apple’s Cocoa, much of the OpenGL functionality is abstracted into a collection of useful structures and related higher-level functions.

For historic and performance reasons, SIO2 is written in C++, not Objective-C. Bridging between pure C++ and Objective-C is not always as straightforward as it should be, and there are a few things to take into consideration when combining C++ libraries with Objective-C.

To aid with that issue, SIO2 comes with a customized Xcode template project, which provides a stable base for beginning the development of an iOS application that combines the SIO2 library with Objective-C and Cocoa. However, it’s not always practical or even recommended to begin all Xcode projects from the SIO2 template, and if you already have an existing Xcode project, it can be a challenge importing the SIO2 library into it. This article outlines the steps needed to import SIO2 into your existing Xcode Objective-C project.

  1. Open your existing Xcode project.
  2. From a Finder window, drag the SIO2 src directory onto your project in the Xcode Groups & Files pane, making sure to select the Recursively create groups for any added folders option in the import dialog box that opens up. Depending on how you organize your third-party libraries, you might also want to select the Copy these items into destination group’s folder option for the SIO2 library. Selecting this option will copy the whole SIO2 library into your project directory. Leaving it unselected will create references to the library. Personally, I recommend leaving this option unselected when importing SIO2. Using references avoids having multiple copies of the SIO2 library spread around your Xcode projects, and allows you to use symlinks to quickly swap out different versions of the library. But it depends on your approach to working with Xcode projects and library code.
  3. In the Xcode Groups & Files pane, rename the new src group to something more informative (like SIO2). In the remaining steps below, I assume you’ve renamed it to SIO2. If you choose a different name, simply substitute accordingly.
  4. In the Xcode Groups & Files pane, under the SIO2/lua folder, delete the swig folder and the file sio2_wrap.c. In the confirmation dialog that pops up, if you left the Copy these items into destination group’s folder option unchecked in Step 2, be sure to delete only the references. Otherwise if you copied the files into your project, go ahead and delete the files as well. If in doubt, just delete the references.
  5. In the Xcode Groups & Files pane, drag the libsio2_dev.a and libsio2_sim.a files in the SIO2/sio2 folder to the Frameworks folder. This action moves the references, not the files themselves.
  6. Here’s where we need to start to compensate for the SIO2 library being written in C++. Compiling now will generate thousands of errors, because Xcode considers all of the SIO2/sio2/sio2*.cc files to be regular C++ files, and does not take into consideration that these files reference some Objective-C syntax via the sio2.h header file. Xcode needs to be told these files are of a different type. We do that in the next two of steps.
  7. In the Xcode Groups & Files pane, select the SIO2/sio2 folder so the contents of that folder appear in the Xcode Detail pane, and sort the list by the “hammer” column so all the sio2*.cc files are grouped together.
  8. Carefully select all the sio2*.cc files (but none of the sio2*.h files) and choose Get Info from the right-click menu. Under the General tab you will see the file type of these files is sourcecode.cpp.cpp. Change this to sourcecode.cpp.objcpp to tell Xcode to expect both C++ and Objective-C code in these files (and any included files).
  9. You should now be able to successfully Clean and Build your project. However, at this point, you will receive several dozen warnings along the lines of warning: deprecated conversion from string constant to ‘char*’. These have to do with some non-strict string casting within the SIO2 library and its sub-libraries, and can be safely ignored. I describe in the following two steps how to configure the Xcode compiler build settings to have these warnings ignored automatically.
  10. Before attempting to change any compiler build settings, make sure the full suite of build settings is visible by setting the active SDK in Xcode to one of the device SDK‘s. If the active Xcode SDK is set to one of the simulator SDK‘s, many of the build settings will not be directly visible in the settings editors. I have no idea why Xcode has this ludicrous limitation, but it is what it is. You can set the active SDK in the Project->Set Active SDK menu within Xcode.
  11. Once you’ve done that, open the Project->Edit Project Settings dialog. On the Build tab, make sure All Settings is selected in the Show list in the header area, then scroll down to the GCC 4.2 – Warnings section. In the Other Warning Flags field, add the value -Wno-write-strings. This field may also be labeled WARNING_CFLAGS, which is the actual compiler flag name. If you cannot find this field, you can add it as a user-defined setting field.
  12. Now Clean and Build your project. If the active SDK is a device SDK, you should get a single warning indicating that the libsio2_sim.a file is not of required architecture. That file is used only by the iOS Simulator, and you can ignore the warning when compiling for a device. If the active SDK is a simulator SDK, you will not see this warning at all.
  13. If you continue to receive a number of further warning messages, this may be due to additional warning settings within the compiler tripping over some of the C++ code within the SIO2 libraries. Make sure the Warning Flags field of the Project->Edit Project Settings->Build tab does not contain any warning flags other than -Wno-write-strings. In particular, make sure it does not contain -Wall (show all warnings). If it does, remove it. Do the same for the the Other C Flags field (aka OTHER_CFLAGS) in the GCC 4.2 – Language section of the Build tab, making sure it does not contain any -W... warning flags (this field may contain other legitimate non-warning flags, so just remove flags starting with -W). Then open the Project->Edit Active Target dialog, select the Build tab, and make sure both the Warning Flags and Other C Flags fields there are free of any unnecessary warning flags. If the Warning Flags field is empty in the Project->Edit Active Target dialog, do not leave it blank, because this will override the -Wno-write-strings setting at the project level. In the Project->Edit Active Target dialog, select Delete Definition at This Level from the choice of edit commands in the lower left corner of the Build tab.
  14. Finally, for SIO2, and Open GL ES in general, there are some important optimizations you should establish via the build settings. In the Project->Edit Project Settings->Build tab, add the following values to the Other C Flags (aka OTHER_CFLAGS) field in the GCC 4.2 – Language section: -fno-regmove -falign-loops=16 -fvisibility=default (this last visibility flag is not for performance, but actually to avoid some other warnings related to function visibility and is included here for completeness on this build setting). Similarly, in the GCC 4.2 – Code Generation section you should turn off the Compile for Thumb settings for both ARMv6 and ARMv7 to improve OpenGL floating point performance. Make sure the settings in the Project->Edit Active Target dialog do not override these settings.

That’s it! There are a number of steps listed here, but I hope I’ve explained them well enough to make them fairly straightforward and easy to follow.






7 responses to “Adding SIO2 to an Existing Xcode iOS Project”

  1. David

    Hi there,

    I am wondering if this is not an old version that you are talking about? I cannot see any of the files or folders mentioned in steps 4 and 5?!?

    1. Hi David…

      You are quite correct. This article was written for SIO2 v1.4. I’ve now updated the article to identify that. Thanks for pointing it out.

      Due to the change in SIO2’s licensing with v2.x, we no longer use SIO2…so I will not be updating this article to cover that product.

      Instead, we are using a new open-source 3D framework written in Objective-C, developed internally here at Brenwill, and built as a full 3D extension to the well-known cocos2d framework. We will be releasing this at the end of next week, and I’ll begin posting articles about it then. If you are an Objective-C developer, it might be worth checking it out.



  2. Pavel Malay

    I can’t find SIO2 v1.4 to download. If you have it, please email me at pavel.malay [a t]!

  3. Hi Pavel…

    This is an older article. As I mention above, SIO2 has dropped support for the 1.4 version.

    I recommend that you have a look at cocos3d instead.


  4. Alexander

    Hi Bill

    Thank you for your job.

    I needed to add a 3d model into my cocos2d project and I created a new project based on the cocos3d template and carried my project into it.
    Everything is good except one thing.

    I use in my project a class CCSpriteScale9 for stretching (tiling) my pictures. I downloaded this class form somewhere. But it works good.
    And now after I add any CC3Node to the CC3Scene my sprites of CCSpriteScale9 becomes invisible.

    Please help.

    Thank you

  5. Alexander


    But property visible of CCSpriteScale9 sprites is YES in NSLog

    1. Hi Pavel…

      This article is not about cocos3d.

      Please post questions about cocos3d to the cocos3d forum, where the community may be able to answer your questions.