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

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:

  1. – Installing required software
  2. – Installing dependencies to make Allegro more useful and to get it compiling (cmake, etc)
  3. – Compiling Allegro for Xcode, installing it and making sure the Frameworks are installed in /Library/Frameworks
  4. – 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
ruby -e "$(curl -fsSL"
  • – 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://

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 - ..
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)
    Xcode new empty project
  • 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.)
    New cocoa application MyGame
  • 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.
      Add new build phase
  • 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)
      add framework headers

    • In the targets Build Settings specify the Framework Search Paths as/Library/Frameworks.add framework search path
      • 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 themadd frameworksselect frameworkslinked frameworks added
    • 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
      drag frameworks to copy build phase
    • 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
      create new main
    • Give it the following content:
#include <allegro5/allegro.h>

int main(int argc, char **argv) {
   al_create_display(640, 480);
   al_clear_to_color(al_map_rgb_f(1, 1, 0));
   return 0;


  • 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:
  • Compiling works fine, linking does not work: Make sure you have specified the Framework Search Paths as/Library/Frameworks.


  1. Thank you so much! The only one worked tutorial!
    Have a question. When I run project – first shows Cocoa’s window(so I assume), not only our project’s allegro window. How can I delete it?

        1. Strange 🙂 But perhaps you can find the difference in your project compared to mine. I have uploaded an Allegro 5.1 project which is like this blog post and this does not open a new window at my Mac. Perhaps you can figure out the difference between that project and yours. I would be interested to know what causes this behaviour.

          You can download it from here:

  2. Why do you use other -> empty Project? I use Cocoa Application and then I select main.xib and the delegate files in the Project Navigator and delete them.

      1. No, no only a other way, now there are three solutions, you can also use the template “commandline tool”.

  3. This is a great guide, and my allegro programs work perfectly on my computer, however, I have a question regarding distribution of a completed program. The Copy Files build phase makes it so that the frameworks are included in the application bundle, but I get a dyld error: framework not found when I open the application on another computer. I believe it’s still trying to find the frameworks in /Library/Frameworks. Is there anyway to have the application work out of the box without needing an installer package to install the frameworks to /Library/Frameworks?

    I already tried to get some help at, to no avail, so I’d really appreciate some help!

      1. For some reason, I ended up with Allegro 5.0.7 frameworks, which didn’t have the correct install_name set in the frameworks. I upgraded to Allegro 5.0.10 frameworks, which did, and then my only problem was a missing libfreetype dependency from the allegroTTF-5.0 framework. I added it to the copy files build phase, used install_name_tool to tell the framework where to find it, and now my application works!

        1. Interesting. Could you perhaps write down how you did this from start to finish? It would be helpful to have a complete guide for that as well. 🙂

  4. Hey, this is a really helpful guide. Just wanted to point out a hiccup for those who may not see it. To install homebrew, you gave the following command:

    ruby -e “$(curl -fsSkL

    This won’t work as-is; it’ll prompt the user with a > which isn’t very self explanatory for those new to CLI. Adding back in the missing )” makes it work just fine. You might want to update the article.

  5. FINALLY! It worked! Also, would you happen to know why xcode doesn’t show any files in the frameworks in the navigator?

  6. I have it working when I run from Xcode, but an archived application cannot run as it can not find the symbol __al_mangled_main. Any clue what is wrong here?

    It would actually be very useful if you could just make a ZIP archive of your compiled Frameworks and offer them for download, and save a lot of time for both yourself and others in the future. For whatever reason I am unable to get it to compile 100% properly on here and it would save a lot of headache if you could!

    1. Hi, great you got it working from Xcode. Not sure about an archive though, it sounds to me you do not include your frameworks in the archive.

      I have thought about offering pre-compiled binaries. But it has drawbacks, since you are required to have all libs/so’s on your system meaning I must require all dependencies of the Allegro binaries and their dependencies etc. Which is quite cumbersome :), also I believe once this works you have a solid ground to work from. I have worked with pre-compiled binaries from other libraries as well and often when you want more than that (ie another library) you most of the time end up needing to compile something.

  7. First of all thank you! I have two questions though.

    For the sample code you provided, xcode had a problem with #include , it wanted the ‘s to be quotation marks. Builded without errors once I made that change. Is this indicative of a larger issue that I had to make that change?

    Secondly, and I think this is what Vlad was getting at in his comment, a little window appears when I run the program. But it’s the same one no matter what code I’m running with (I’ve only tried a few of the sample programs on the allegro site). Maybe these two issues are connected?

    1. Hi, glad it was of some help for you.

      About single and double quotation marks, I have never encountered such issues before so I presume this lays somewhere else. Could you be more specific which files where required to change? Do you mean the example code at the end of the post? (the #include ?)

      About running the program: thats indeed odd. I have played around with the source code and could make changes (ie change background color, or add rectangles, etc). I did not try the examples myself. If i get the chance to work with them I will post some more info about that.

  8. Hi Stefan,could help me out,i need to install Allegro 4.4,so following your tutorial,after this step :
    ‘git clone git://’

    I run the following command:
    ‘git checkout 4.4’ (I believe this switches the version to 4.4)

    The things is that after the whole procedure the Frameworks aren’t compiled.After this step:
    I’m getting the following error:
    ‘The following build commands failed:
    CompileC build/ src/macosx/main.m normal x86_64 objective-c’

  9. In “Header Search Path” you have
    for AllegroColor addon, should be
    (with “s” in the end)

  10. Hey Stefan the guide was pretty helpful and i followed everything in the guide but the header AllegroTTF-5.0.framework is missing in my frameworks file do you know why this could have happened and i am using allegro 5 , might this be the reason

    1. Hi Sree,

      Good question. I have not tried this with Allegro 5.0. However, I do know that if your system does not have the nescesary dependencies the makefile that is generated to build Allegro will leave out any components it cannot make. Ie, try to install ttf you need the dependency “libfreetype6-dev”. This I got from so its probably a bit different for Mac OS X. If you use brew try using ‘brew install freetype’ or something along those lines.

      After this you probably need to redo quite a lot of steps from this guide. You need to generate a new makefile for Allegro, then build it again, and so on. Let me know if you run into any troubles.

      1. hey i tried out what you pointed out but still the library was missing , so i deleted everything and installed it from the start using allegro 5.1 and i still got the same error any idea why this is happening

  11. For the people trying out 5.1 and just getting started with Allegro your path needs to be ” /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/AllegroMemfile-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroPhysfs-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroPrimitives-5.1.framework/Versions/Current/Headers /Library/Frameworks/AllegroTTF-5.1.framework/Versions/Current/Headers ” Not use the one above that has 5.0 in it

  12. When I build, it says it can’t find allegro.h, even though I have copied all 12 files to my header search paths and set frameworks search path to library/frameworks. Please, any thoughts?

  13. For anyone having problems with FreeType not being found during cmake, (LEading to allegro_ttf failure), do a brew install Freetype, and then if it keeps not finding it (My case), type the following line on command tools:

    ln -s /usr/local/opt/freetype/include/freetype2 /usr/local/include/freetype

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.