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
Objective-C. Bridging between pure
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
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.
- Open your existing
- From a
Finderwindow, drag the SIO2
srcdirectory onto your project in the
XcodeGroups & 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
Xcodeprojects, and allows you to use symlinks to quickly swap out different versions of the library. But it depends on your approach to working with
Xcodeprojects and library code.
- In the
XcodeGroups & Files pane, rename the new
srcgroup 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.
- In the
XcodeGroups & Files pane, under the
SIO2/luafolder, delete the
swigfolder 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.
- In the
XcodeGroups & Files pane, drag the
ibsio2_sim.afiles in the
SIO2/sio2folder to the
Frameworksfolder. This action moves the references, not the files themselves.
- 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
Xcodeconsiders all of the
SIO2/sio2/sio2*.ccfiles to be regular
C++files, and does not take into consideration that these files reference some
Objective-Csyntax via the
Xcodeneeds to be told these files are of a different type. We do that in the next two of steps.
- In the
XcodeGroups & Files pane, select the
SIO2/sio2folder so the contents of that folder appear in the
XcodeDetail pane, and sort the list by the “hammer” column so all the
sio2*.ccfiles are grouped together.
- Carefully select all the
sio2*.ccfiles (but none of the
sio2*.hfiles) 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
Xcodeto expect both
Objective-Ccode in these files (and any included files).
- 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
Xcodecompiler build settings to have these warnings ignored automatically.
- Before attempting to change any compiler build settings, make sure the full suite of build settings is visible by setting the active
Xcodeto one of the device
SDK‘s. If the active
SDKis 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
Xcodehas this ludicrous limitation, but it is what it is. You can set the active
SDKin the Project->Set Active SDK menu within
- 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 Flagsfield, 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.
- Now Clean and Build your project. If the active
SDKis a device
SDK, you should get a single warning indicating that the
libsio2_sim.afile 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
SDKis a simulator
SDK, you will not see this warning at all.
- 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 Flagsfield 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 Flagsfield (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
Other C Flagsfields there are free of any unnecessary warning flags. If the
Warning Flagsfield is empty in the Project->Edit Active Target dialog, do not leave it blank, because this will override the
-Wno-write-stringssetting 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.
- 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
visibilityflag 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 Thumbsettings for both
ARMv7to 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.