Okay, so opinions might be divided on the iPhone as a communications device, but it’s only a blind burns victim that couldn’t appreciate the visual and tactile charm of Apple’s latest marvel. While the high cost and extortionate monthly contract may have hidden this tech from all bit the richest, the identically-specced iPod Touch has brought that technology to a much wider audience.
Knowing that, it’s tempting to start thinking how games could make use of some of those high-end features, like the multi-touch screen and surprisingly accurate accelerometer. The first hurdle threatening to derail your thought train is that, at the moment, the iPhone/iPod Touch are both closed platforms. Although Apple has finally turned around on its stance, promising an SDK this month, at the time of writing nobody knows exactly what form that will take, and exactly how open the company will be on letting third parties have access to iTunes distribution (our guess: not very).
Although we can’t answer those questions here, we can look at a current alternative: the unofficial SDK developed by a group of clever hackers. But unlike the image an unofficial SDK may conjure up – messy, undocumented, reverse-engineered code – this SDK is cobbled together from Apple headers and is likely to be similar to whatever does eventually find itself released as official.
What follows is a whistle-stop introduction to getting your first app running on an iPhone. Unfortunately, due to space concerns, we’ll have to delegate many of the steps to walkthroughs available on the Internet, but you’ll at least have a clear path to getting some custom code on the platform, as well as a host of pointers on where to go from here.
First of all, we’ll assume you have a ‘jailbroken’ iPhone (or iPod Touch - we’ll use the word iPhone hereafter to refer to both), running firmware 1.1.2. If you’ve not done this yet, there’s countless guides out there on the internet, so a quick Google will reveal several good places to start.
The next step is getting the toolchain set up. Precompiled binaries are available for both Windows and Mac to hugely reduce the setup time. Mac users can use Apple’s Xcode IDE to develop with, whilst Windows users will have to reply on GNU make and Cygwin.
AN OBJECTIVE-C PRIMER
Just to make matters a little more difficult, Apple’s programming language of choice is the niche C object-orientated spin off Objective-C. To give a full treatise of the language here is beyond the scope of the article, but any OO-accustomed programmer can quickly get up to speed by observing the following notes.
At its core, objective C is a weakly typed language – all object references are actually of the built-in type id, regardless of what object they’re pointing to. As such, you could actually create all of your objects as ids, but it’s preferable to use the C-style syntax depicted below for two reasons: firstly, explicitly stating the type increases code clarity, and secondly, doing so allows the compiler to check for errors at build-time.
// is technically the same
// as, but less clear than:
Classes are defined in header files (with extension .h) and implemented in .m files.
// example.h - a simple class
// put instance variables here
// - denotes an object method (non-static)
– (int) doSomething: (int) val;
// + denotes a class method (static)
+ (void) doSomethingElse;
– (int) doSomething: (int) val
return value * passedValue;
Objective C is based on the paradigm of passing messages to objects instead of caling their methods or accessing their data. So, supposing we had an initialised instance of MyClass called obj, we’d invoke the doSomething method by writing
[obj doSomething: 4];
Parameters can be named to enhance code readability (with the exception of the first parameter, the label for which is often embedded into the method name), such as the following hypothetical example:
int result = [mathHelper pythagorasWithBase:3 side:4];
Objects are created by allocing them, which initialises all instance variables to their default value. As such, classes often provide an init method that acts similar to a C++ constructor:
MyBetterClass* better = [[MyBetterClass alloc] init];
The above example shows a main point about Objective-C: that messages can be (and often are) nested. In the example, the result of the [MyBetterClass alloc] call is the id of the allocated object, which is then used as the object on which the init method will be called.
Finally, Apple’s SDKs include their own string object, NSString, and all of the frameworks use it. A feature built into the language enables you to quickly turn a string literal into an NSString object with the @ character, which you’ll need to use often with the framework functions, as in the following example:
[textLabel setText: @”This is a text label”];
Objective-C’s syntax may appear confusing at first, but it’s important to remember that as a pure subset of C there’s largely familiar territory hidden under all that new punctuation. The above pointers should give enough information to make most Objective-C code readable, and any remaining gaps should be more than ably filled by Apple’s comprehensive Objective-C documentation.
Now that we’ve got some Objective-C skills under our belts, the next step is to examine and compile a Hello World example and get it running on the machine. Erica Sadun’s simple Hello World app is a great place to start – it’s largely self-explanitory and cleanly written. Simply copy the text into the four named files and run make at your OSX/Cygwin terminal prompt (although HTML formatting will turn the tabs in the makefile to spaces, so replace any tabs to ensure that the make process works correctly).
<?xml version=”1.0” encoding=”UTF-8”?>
<!DOCTYPE plist PUBLIC “-//Apple Computer//DTD PLIST 1.0//EN”
Once the build has finished, you’ll be left with a SampleApp compiled file. The only step remaining is to bundle this application and deploy it to the device. Mac users should have little problem doing the bundle with Xcode, but Windows users will need to do so by hand. The first step is to make a directory on your dev machine called [AppName].app, so SampleApp.app in this instance, and copy your binary into the folder alongside a 57x57 PNG called icon.png for the app’s icon, and optionally a 320x460 PNG called default.png that’ll be displayed while your app loads.
The last part of the bundling process to add an XML file called Info.plist that tells the OS a little about your application (note the capital I - very important). Below is a sample Info.plist that’ll work for our Hello World example.
The only two items you’ll need to vary on that list are CFBundleExecutable, which should always point to your binary’s name, and CFBundleIdentifier, which can be whatever you’d like. Once you’ve done this, you’re ready to copy the whole folder over to your iPhone’s applications directory, which is usually ~/Applications/ unless you’ve moved it. To copy the file over, download the BSD Subsystem and OpenSSH packages from the Installer app that was placed on your iPhone when you jailbroke it.
Then use an SSH program to connect to the device, using the iPhone’s IP address (found in the Settings menu), username ‘root’ and password ‘alpine’ (by default). The final step is to change the permissions on the compiled file to make it an executable – you can either do this via SSH or on the iPhone itself using MobileFinder. After this, your app should show up in the main menu – if it doesn’t, try resetting the device or using the ‘respring’ function of SysInfo, which can be obtained from the Installer.
And that’s it! If there’s been any problems, the lack of a debugger may render finding the problem difficult, but there are two courses of action. First, detailed crash information can be found in the ~/var/logs/CrashReporter folder, and secondly, you can use NSLog() to print debug messages that will show up if you run the program from an SSH prompt.
From here, I’d recommend checking out some of the open-source games hosted at Google Code such as FiveDice for sprite-displaying code, and don’t forget that the iPhone runs OpenGL ES v1.1. Initial experiments showed that OpenGL didn’t play very well with the UIKit, but the community has made a UIGLView class that makes using OpenGL as simple as subclassing the provided class for your view object and overriding the drawRect method. Armed with that, you should be ready for some coding.
Ed Fear is Develop’s staff writer and resident technological tinkerer. His first iPhone app, a work-in-progress port of the Japanese flash card program JFC, can be found at ijfc.googlecode.com. Both he and Develop take no responsibility should any damage come to your computer or device by following these instructions.