Gb Se

Mac frameworks for common game libraries

Table of contents

What's this now?

MacOS is not Unix. It supports the Unix way of thinking and programming, but it's certainly not the way Mac coders code. Mac coders close their eyes, sigh heavilly, clench their teeth and hands momentarily, and then type unnecessarily hard on their aluminum-colored plastic keyboards whenever there's a library that a) requires manual compilation when a regular mpkg would've been fine b) requires setting up include and linker paths (especially if in a Makefile) c) ends up as an .a or .dylib and a bunch of loose header files that require the user (i e the coder in question) to place these in special locations and keep track of them and setup path strings in projects and....

Because on a Mac, we use .frameworks, which we blissfully drag into our project windows and never bother about again. They're also very handy when distributing application dependencies, because you can just drop them into the application bundle.

However, many open-source projects lack .xcodeprojs for their projects, even though they claim Mac compatibility, and thus don't compile nicely into .frameworks. This is often easy to remedy by making one manually. If you want to know how, scroll to the bottom. If you're lazy, I've put together a list of the ones I've .frameworkified myself, and others that I've found around the net.

Hope this helps!
 - Joachim Bengtsson

List of .xcodeprojs and .frameworks for common game libraries

RakNet

RakNet is a pretty good networking framework that does its efficient magic over UDP (and adds its own reliability checking and stuff like that).

It seems they broke my project with 3.001. I've updated the project accordingly, and repackaged as one big nice zip with sources, xcodeproj, and prebuilt frameworks for both debug and release. .

  1. Download RakNet v3.001 with source, project and binaries.
  2. Install the prebuilt framework from Mac/build/(Debug or Release)/ into /Library/Frameworks or YourGame.app/Contents/Frameworks/, or...
  3. Open the xcodeproj and rebuild the Debug framework to get source traces when you crash in the library, or...
  4. Replace the sources with those of a newer version and then build your own.

Old downloads: RakNet30Beta.zip + drop-in xcode project; sources and xcodeproj for 2.457; Release .framework for 2.457

ODE (Open Dynamics Engine)

ODE is a physics simulation engine that some people say isn't as good as Newton, but personally I have no idea which is best.

I'll add instructions and binaries for ODE next time I use the library.

OGRE (Object-Oriented Graphics Rendering Engine)

OGRE is a graphics engine for games. Will Thumbleby has a great Mac port of it.. I have a ton of different compiles of this fw, for several versions and both platforms. Mail me if you need anything.

FreeImage

FreeImage is a library for loading image files in a variety of formats (PNG, BMP, JPEG, TIFF and many others). OGRE used to use DevIL for this task, but they use FreeImage nowadays, which is why I use FreeImage in my own (cross-platform) games. It's neat in that it bundles all its dependencies, and thus has no external dependencies.

  1. Download FreeImage 3.9.3 (Source distribution)
  2. Download my FreeImage xcodeproj
  3. Unpack both, put the contents of the second into the first
  4. Open the xcodeproj, build.
  5. Place the result in /Library/Frameworks

Alternatively...

  1. Download my cached version of the FreeImage 3.9.3 source that includes the mac proj
  2. See 3-5 in the above

Alternatively...

  1. Download my prebuilt Release .framework.
  2. If you need debugging symbols for when you're developing with the framework, you probably need the source as well, so go with alt 1 or 2 above

GLEW

GLEW is "The OpenGL Extension Wrangler Library". It is a cross-platform library that handles all your extension needs in a nice and simple API.

  1. Download GLEW 1.4.0 with source, project and binaries in one lazy package.
  2. Install the prebuilt framework from Mac/build/(Debug or Release)/ into /Library/Frameworks or YourGame.app/Contents/Frameworks/, or...
  3. Open the xcodeproj and rebuild the Debug framework to get source traces when you crash in the library, or...
  4. Replace the sources with those of a newer version and then build your own.

I have no idea why I messed around with lots of "alternative" downloads in the frameworks above, this is much easier.

Update: GLEW 1.5.0 with source, project and binaries

SDL

SDL is already well-ported and can be downloaded through their site. However, SDL is often used together with a few support frameworks. Thus, I'm bundling them together for you in one easy package here. The unusual one is SDL_gfx, which has no good official Mac port (at least not Universal).

  • SDL.framework
  • SDL_gfx.framework
  • SDL_image.framework
  • SDL_mixer.framework
  • SDL_net.framework
  • SDL_ttf.framework

Download SDL with friends

YAML/libsyck

YAML Ain't Markup Language, but a serialization standard. Think of it like XML done right, and human friendly. What is not as human-friendly is their Mac port deployment. It wasn't universal, nor gc-enabled, so I tried building from source. This required building from command line and... Yeah. I've built it as a four-way universal binary with garbage collection enabled. This means that you can link to it in a 10.5 GC app, but it also means that it's completely untested. The GC might make the parser go crazy, or the other way around. Use with some care.

Also, note that this is based on Will Thimbleby's syck port, and not the new yaml libraries ("libyaml"), so it might not be able to parse everything.

Download YAML.framework + sources, based on syck 0.55

How can I create proper .frameworks myself?

Some projects employ fancy shell scripts and configure scripts and all kinds of magic in order to compile. Such projects are tricky to make .frameworks of, at least with XCode (I'm much too lazy to learn how to do it with gcc). If that's not the case, the process is rather straight-forward.

  1. Download and unpack the source code for the project in question
  2. Create a new XCode project, calling it by the same name as the project you downloaded, but setting the path for it to something like /path/to/downloaded/project/folder/Mac/
  3. Create a new Framework target
  4. Drag all the source code files into the project
  5. If the project has all their header files in a separate folder, add this folder under "User Header Search Paths" in the target's info (cmd-opt-E). The path will be relative to the xcodeproj file, so it's likely something like "../inc/"
  6. You might want to change the Installation Directory. If you're going to install the framework into the end user's Library folder, type in "/Library/Frameworks/". If you're going to bundle it in the application bundle, type in "@executable_path/../Frameworks/". This is rather important.
  7. Build and be happy!

How do I properly embed .frameworks in my application bundle?

No matter if the library is open source, closed source or has a good install_name, following these procedures will properly bundle it in your app. These instructions are taken from my blog entry on the subject.

  1. Add an extra Copy Files target action in your XCode project (and rename it Copy Frameworks)
  2. Get info on the new terget action, and set its destination to Frameworks.
  3. Then, drag all custom frameworks to this target action, and they will be automatically bundled with the application when you build.
  4. You will now need to gather some information. Run `otool -L on YourApp.app/Contents/MacOS/YourApp` and note its output for each of the lines corresponding to a framework you just bundled.
  5. Next, add a Shell Script target action. This target action will call the install_name_tool to rewrite the linking information in the built binary to reference the bundled frameworks instead, even if the frameworks haven't been built with an install_name of @executable_path/../Frameworks. Copy and modify as appropriate:
function relocateLibraryInCurrentApp() {
  install_name_tool -change $1$2 @executable_path/../Frameworks/$2 $CONFIGURATION_BUILD_DIR/$EXECUTABLE_PATH
}

relocateLibraryInCurrentApp /usr/local/lib/ libfmodex.dylib #note the space
relocateLibraryInCurrentApp /Library/Frameworks/ Foobar.framework/Versions/A/Foobar #note the space

Note the two different styles for a loose dylib and for a .framework. Just add one relocateLibraryInCurrentApp for each library or framework you're bundling. Good luck!