Compiling Frogatto on iOS

(work in progress - was written around iOS 4.3)

Acquiring and Packaging Libraries and Frameworks:

For undisclosed reasons (likely security) Apple has disable dynamic-library inclusion in an app bundle, as you would do on Mac OS X. Nor can you link to any system dylibs besides those provided by apple; thus, any libraries need to be either statically linked or need to have their source files directly compiled into the application. Solutions for each library are a bit different, and are posted as follows:

OpenGl

Apple provides OpenGL ES as part of the OS. OpenGL ES requires different includes than OpenGL; Desktop OpenGL typically requires inclusion of GL/gl.h; whereas OpenGL ES requires inclusion of TODO. In order to have a minimal impact on our source code, and also to conveniently integrate something SDL 1.3 already includes via its OpenGL backend, we forego what would be the usual solution: a compiler directive which detects if we are running on iOS, and selectively includes either

libboost_regex.dylib, libboost_iostreams.dylib, libboost_system.dylib

Acquire these files from http://www.boost.org/ The latest version as of this writing is 1.47.0. You're looking for a large zip file full of source code files and such. Unlike for the mac version, you won't be compiling these into libraries using boost's built-in tool; you'll instead be putting the source files for the libraries we want, directly into XCode.

The source files for each of these, by the subnames "regex", "system", and "iostreams", can be found in e.g. boost_1_47_0/libs/regex/src; drag everything in each folder into a new group in XCode's file listing.

To reference the header files, assuming the above "boost_1_47_0" folder extracted from the archive is present in the same folder as our XCode project, then add the header path "./boost_1_47_0/"

GLUT (as iphone-glu, or iGLU)

(Not to be confused with GLEW.) Unlike for desktop macs, GLUT is not available as a direct part of the OpenGLES available on iOS; we use some parts of it, though. Someone with a similar problem has made a re-creation of it which covers everything we need. You can download the files from http://code.google.com/p/iphone-glu/ - it's suggested you grab the iGLU-1.0.0.tar.gz release. From that, we want to make a libGLU.a file by running their makefile, and we want to have the library's headers accessible in a local directory to our project file. Their makefile is hard-coded for a specific release of the iOS SDK. You can find and correct this file at iGLU-1.0.0/configs/darwin-iphone. It also only builds for one architecture, and we need a combined "fat binary" containing both armv6 and armv7. To do this, we'll need to first build copies for the library for each architecture using the suggested makefile invocation on their website: make ARCH=armv6 PLATFORM=iPhoneOS Note that between invocations of make, you'll need to "make clean" to remove your armv6 files before building the armv7 ones - otherwise even though you issue the command to rebuild the library with ARCH=armv7, it will naively build it from the already-constructed armv6 object code.

I suggest doing this for both armv6 and armv7, and putting the resulting libGLU.a file from each in a respectively-named folder, for the combination step. Apple provides a tool named lipo to combine libraries of one architecture into libraries containing multiple architectures. If we use the following line, it'll combine both of the libraries we just created into a fat binary suitable for use: lipo -arch armv6 armv6/libGLU.a -arch armv7 armv7/libGLU.a -output libGLU.a -create

Once this fat binary libGLU.a file is created, drag it into the "Frameworks" group in the left-hand-side XCode file navigation sidebar.

libSDL.a

SDL needs to be compiled from source; at the moment, we're using the development builds of 1.3 from http://www.libsdl.org/hg.php Download the zip file, and the resulting archive will come with makefiles for various platforms, including an xcode file for iOS. Consult their readme, but loosely you'll want to open that xcode file, and select the build scheme that targets the product "libSDL.a"; to find the products of this, right-click on the "Products->libSDL.a" item in the left-hand navigation bar in XCode, and select "Show in Finder"; this will reveal a folder containing both a libSDLa file, and nested directory usr/local/include/* with a bunch of header files in the bottom-most folder; since this bottom-most folder is all we want, and the other folders were empty, I put both the "libSDL.a" file, and the "includes" folder in a new directory at the same location as the XCode project file for Frogatto, named "SDL". The header search path for this was "./SDL/include". Note that SDL's XCode project will by default create a fat binary; if in doubt, "lipo -info filename.a" will display what's in a library.

Once this libSDL.a file is created, drag it into the "Frameworks" group in the left-hand-side XCode file navigation sidebar.