A few people have shown interest in running RakNet on the iPhone, and the term appears at least once a day on my “Search Engine Terms” stats column. I initially planned on just putting up a package containing an Xcode project and a few of the RakNet samples, but I’m not sure how this would work with the license agreement. To be safe, I’ve written a general tutorial here instead of posting any of the RakNet source.
One of the common ways to include an external package on Mac is to use a Framework, however this option is not available for the iPhone. This means that there are only really two ways to get RakNet into an iPhone application: compile it directly as part of the project, or link it as an external library.
The first option is definitely the easiest to set up; all you need to do is copy the RakNet files into your project’s source code directory and then include them in the Xcode project as you would any file. This is the route I initially took in my own integration, but I’ve since switched to using a library. I’m not going to cover this method here as it’s pretty straight forward to use, but if you want to use it and have trouble I’m happy to help.
The second option, the library, generally requires that you setup a second Xcode project specifically for building the RakNet library. It also requires that you compile separate versions for the iPhone Simulator and iPhone Device, since they have different CPU architectures. A helpful comment from Paul Solt on an earlier post showed how these two versions can be compiled into a single library; I’ll cover that here as well.
So, onto the tutorial.
The first step is to open up Xcode and create a new project. From the iOS sub group, you’ll want to select “Library”, and then “Cocoa Touch Static Library”, like so:
Go ahead and create the project. I called my “Test” in the screenshots here, but you’ll probably want to go with something along the lines of “RakNetLibrary.”
The next step is to input the source from RakNet into your new project. Right click the “Classes” folder and go to Add > Existing Files…
In the menu that comes up, navigate to the folder containing the RakNet source code. This doesn’t have to be in your project directory, since we’ll tell Xcode to copy the files over. Select all of the files, but don’t include the “cat” folder. This isn’t needed for most RakNet use cases, and does not compile on OS X as of yet.
After selecting the files and clicking “Add”, make sure the window that comes up has the following settings:
At this point, you’re ready to compile. Go to the “Build” item on the toolbar and select “Build” from it, or hit command-B. There are a hundred or so warnings that show up, but these aren’t serious and are just from missing #directives and a macro redefinition. It’s possible they’ve been fixed in builds of RakNet after this tutorial was posted.
A commenter, Richard, has pointed out that with the newer versions of Xcode there’s a problem with one of the compiler settings. The problem occurred for him with Xcode 4.2, but if you have trouble with any version of Xcode 4.0+ you might want to check into this. Richard says:
The problem turned out the be the compiler, for previous versions of the SDK the default compiler is “LLVM GCC 4.2” however for the new SDK I guess the default compiler is “Apple LLVM Compiler 3.0”. For whatever reason Apple LLVM Compiler 3.0, cause the errors and many extra warnings.
You’ll want to set your compiler version to GCC 4.2, which is located in the Project settings. To do this, right click the project, select Get Info and scroll down to the section labeled Compiler Version.
After the build is finished a file named “lib.a” will be created. This file is by default in the build/Debug-iphonesimulator/ folder by default, but will depend on what settings you used to build the project.
At this point the library is useable, however you’ll most likely wanted to compile a Device version as well. The device and simulator versions can be combined into a single universal binary using lipo, a tool included on the Mac. Assuming your device library is _d and your simulator library is _s, you can create a universal binary by running the following in Terminal:
lipo -create libTest_d.a libTest_s.a -output libTest_u.a
At this point, the library will be useable for any iOS development you do, whether it be on the simulator or device.
To include the library in an iPhone project, I generally add it to the “Frameworks” folder along with the other Cocoa frameworks. Right click that folder and select Add>Existing Items in the same fashion that you did for the RakNet source files. Since the file is only a library and does not contain any header information, you’ll also need to add references to the RakNet header files. This can be done by adding the RakNet source folder to the header search paths. Right click on the project, and select Get Info. From there, scroll down to the “Search Paths” section and double click the Header Search Paths entry:
Add the folder that contains your RakNet source code to the list, which is most likely empty on a new project. This should be all you need to get going with RakNet!
Since this post has become rather long, I’m going to do a second one tomorrow with some examples of how to actually use RakNet to set up a simple chat client app for the iPhone that can communicate with the RakNet Chat Server example.