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.