Tutorial : RakNet for the iPhone

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:

Once everything is set, click Add.

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.

T

Advertisements

11 responses to “Tutorial : RakNet for the iPhone

  • Anon

    Thank you soooo much ! i was looking all over on how to do this. every where I went just said they are using it, and when asked how; no one would answer (even on the official forums of Raknet !). This should be included with the download, it seems stupid that its not, to me anyway. Especially since they advertise iOS support, you think “they” would supply the build for iOS, instead of everyone having to figure it out.

    Cant wait for the examples post, hopefully tonight. Thanks.

  • Taylor Petrick

    Hey,

    Glad you found it helpful! And I agree with you, I’m going to submit this code and the examples to the RakNet developers for review in hopes that they’ll include it in the official packages. Likewise for Mac versions, since they advertise support for that as well.

    The code for the examples is more or less done, I just need to write up the explanation. It should be up later tonight.

    Taylor

  • Tutorial : RakNet Chat on the iPhone « Taylor Petrick's Blog

    […] going to assume you’ve completed the last RakNet tutorial and have compiled RakNet into an iPhone library. We’ll be using that library again here in […]

  • Richard

    Great tutorial, however this is not working for me 😦

    I created a new Static Library iOS project, added the RakNet Source (excluding the .vcproj files and cat directory), now in the tutorial it says it should be good to build but i get the warnings :

    No previous prototype for function
    Enumeration value not handled in switch
    Unused variable

    and I also get the error :

    Call to function that is neither visible in the template definition nor found by argument-dependant lookup.

    Just a couple questions, what version of Raknet are you using, I have RakNet_PC-4.031 ? could you email me your Xcode project for the library ?

    Thanks.

  • Taylor Petrick

    Hey Richard,

    Sure, I can send the project file. I’m using version 4.031 as well, so that should be the problem.

    What type of Mac are you using, Intel or PowerPC? On the RakNet forum there was some discussion about RakNet not compiling properly on PPC, so that could be the problem if you’re on a PPC Mac.

    Taylor

  • Richard

    Im using an Intel so thats not it, ill look at the project and see if there is any differences I’m not seeing and I’ll let you know. My email is xxp0k3rxx(at)gmail(dot)com thanks Taylor.

  • Tutorial : RakNet Replica3 on the iPhone « Taylor Petrick's Blog

    […] going to assume that you’ve looked at the previous tutorials using RakNet, and have at least compiled an iOS RakNet library. We’ll need to use that to compile the application in this […]

  • qingyiquan

    libRakNetLib.a, missing required architecture i386 in file
    what should i do?

  • Taylor Petrick

    Can you be a bit more specific about where/when the error is occurring? Is it during compilation of the library itself, or linking with the library in an external project?

    The architecture error makes me wonder if perhaps you’re trying to link it with a Mac project; this tutorial is only for iPhone, and the resulting libraries will only compile into projects set for the iPhone build target.

  • qingyiquan

    thanks for your reply,I compile raknet directly as part of the project,and it works!so,I decise to use that way.

  • Brendy

    At last, sonoeme who knows where to find the beef

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: