January 2013 – Stefan Hendriks' blog

In Dune 2 – The Maker, I have used Allegro quite a bit. Back then it was around version 4.2. Allegro is a library that allows you to make games. In essence it has functions for manipulating the screen (ie, drawing bitmaps, manipulating palettes, etc), use controls (mouse, joystick, keyboard, etc) and more. With plugins you could extend it further, to use fonts (TTF), networking, etc.

Currently, the most recent version is Allegro 5 which breaks with the Allegro 4 API and makes it impossible to convert from Allegro 4 to 5 (atleast for D2TM). From a nostalgic perspective I wanted to try Allegro 5 and on my new system which runs Mac OS X 10.8.

In this post I will describe how you can get Allegro 5 working on Mac OS X, under XCode 4.5. I had great help from the documentation provided, and hopefully this post is sufficient for you. If not, I would suggest to checkout this documentation, or this one.

Rough steps

To give you an idea what we’re going to do, here is the installation in very rough form:

– Installing required software
– Installing dependencies to make Allegro more useful and to get it compiling (cmake, etc)
– Compiling Allegro for Xcode, installing it and making sure the Frameworks are installed in /Library/Frameworks
– Setting up an Xcode project to test if Allegro works

Prerequisites (Installing required software)

Requirements for getting started, if you already have this installed you can skip the prerequisites

Mac OS X 10.8
Xcode 4.5 (with command line tools)
Git/SVN
Homebrew

Before we can start, we need to have installed some prerequisites. Which are Xcode (you can get this from the App store), git and svn. I have used homebrew to install dependencies, you can also use Macports but I do not have any experience with this. (as far as I can tell it should behave quite the same). My advice would be to install these in the following order:

– Xcode
– Install command line tools from Xcode

in Xcode, go to preferences, tab "Downloads" -> " Components" -> Command Line Tools

– Install homebrew

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

– The command line tools should have installed git and svn for you, try them out:

hit "svn --version", and "git --version" in your terminal.
If they are not installed, you could install them via homebrew (brew install git && brew install svn)

Installing required dependencies

As suggested by the Allegro 5 wiki we need to install dependencies. The wiki explains how to do it with Macports, but since I am using Homebrew, you need to do it like this:

brew install cmake

brew install zlib
brew install freetype
brew install jpeg
brew install libogg
brew install physfs
brew install libpng
brew install flac
brew install ffmpeg

The first one is cmake, which we will need to build Allegro. Cmake is required to create the OS specific build steps to compile Allegro, without it we cannot proceed. The other dependencies are used to make Allegro more useful. When we prepare to build Allegro in the next section, cmake will check what dependencies are installed. The more it finds, the more features it will provide in Allegro 5.

Note, you might get a warning about zlib. If thats the case, you can ignore it.

Compiling Allegro for Xcode, and making sure the Frameworks are in /Library/Frameworks

Once we have everything set up, this step is relatively easy. Since we are going to compile it for Xcode, we basically are doing the same as the Allegro wiki is saying.

Open a terminal, and go (cd) to a directory where you want to get allegro’s sources. For example: ~/projects

cd ~/projects

We now need to fetch the sourcecode of Allegro, which we can do by using git clone. At this moment of writing, Allegro 5.1 is the current version. Our git clone command looks like this:

git clone git://git.code.sf.net/p/alleg/allegro

This takes a little while. Once git is done, you have Allegro’s sources in ~/projects/allegro.

Now: cd to allegro, and create a new directory called “build”, then go into that directory.

cd allegro
mkdir build
cd build

The first step is to let cmake (the first dependency we installed) prepare our build, then build it and then install it. This is done by the following:

cmake -G Xcode -DWANT_FRAMEWORKS=1 - ..
xcodebuild
sudo xcodebuild install

The last step requires you to enter your password.

I found that the last step did not work for me, in order to fix that I did:

cd lib/RelWithDebInfo

Within here all Frameworks are built. Now copy them over to your /Library/Frameworks directory with sudo. With this:

sudo cp -r *.* /Library/Frameworks/

If you don’t want to copy this over to your Library/Frameworks directory, then you need to remember the path to these frameworks as we are going to need them later.

Setting up an Xcode project and see it all working

This section is a copy & paste + improvement from this page.

Start XCode, create a new empty project (Other->Empty)
Add a Cocoa Application target to the project, let’s call it MyGame. (Click your project, then the + button at the bottom saying Add target, then Mac OSX->Application->Cocoa.)
Select the MyGame target, go to the Build Phases tab and add a new Copy Files Build Phase (+ button down right).
- Select Frameworks from the dropdown
- Leave Subpath blank
- We leave this build phase empty for now, we will need it later.
Select the Build Settings tab then:
- Note: You can change display from Basic to All at the top and use the search box to locate the following settings
- Change Header Search Paths to (just copy & paste):
```
/Library/Frameworks/Allegro-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroMain-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroAcodec-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroAudio-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroColor-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroDialog-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroFont-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroImage-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroPhysfs-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroMemfile-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroPrimitives-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroTTF-5.1.framework/Versions/Current/Headers
```
  (yes, it is intended to be one line)
- In the targets Build Settings specify the Framework Search Paths as/Library/Frameworks.
- - This is needed to have cross-platform code (#include <allegro5/allegro.h> working – otherwise paths like using #include <Allegro-5.0/allegro5/allegro> would work without changing the search path)
  - If you use another location, one way to save on typing is to double click the input field, then navigate to the Headers folder in each framework and drag it into the xcode input list
- Delete Prefix Header (Edit->Delete)
  - You can of course use your own prefix headers – but the default Cocoa one will only work with objective C projects that’s why we remove it, assuming MyGame is a cross-platform C/C++ project
Add all the Allegro frameworks as follows (this can be done in many ways, a group just keeps things tidy):
- Select the Summary tab
- Click the + button under Linked Frameworks and Libraries and add all the Allegro frameworks
  - In case they are not listed use the Add Other button and navigate to /Library/Frameworks to find them
- Go to the Build Phases tab, then in the list to the left select all the Allegro frameworks and drag them to the Copy Files entry which we added before
- Select all the frameworks again and this time drag them to the Frameworks group to the left (just to have things more tidy)
Don’t forget to remove the created source files under MyGame and add your own source code instead (note the main.m in Supporting Files for example)
- Create a new main.c
- Give it the following content:

#include <allegro5/allegro.h>

int main(int argc, char **argv) {
   al_init();
   al_create_display(640, 480);
   al_clear_to_color(al_map_rgb_f(1, 1, 0));
   al_flip_display();
   al_rest(5.0);
   return 0;
}

Caveats

Cannot find header files: Make sure you have set the header paths correctly. Try to copy the one line given above, into your header paths (remove old ones first). If that does not work. Try adding them one by one, to make it easier to copy/paste I have provided them for you separately as well:

/Library/Frameworks/Allegro-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroMain-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroAcodec-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroAudio-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroColor-5.1.framework/Versions/Current/Header
/Library/Frameworks/AllegroDialog-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroFont-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroImage-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroPhysfs-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroMemfile-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroPrimitives-5.1.framework/Versions/Current/Headers
/Library/Frameworks/AllegroTTF-5.1.framework/Versions/Current/Headers

Compiling works fine, linking does not work: Make sure you have specified the Framework Search Paths as/Library/Frameworks.

Month: January 2013

Getting started with Allegro 5.1 on Mac OS X 10.8 (Xcode 4.5, and homebrew)

Share this: