Allegro 5.0 on Mac Snow Leopard

For more notes on Allegro 5 on Lion and Xcode 4 see this post.

I had been experimenting with Allegro 4.4, but now Allegro 5.0.0 has arrived. Apparently version 5.0 has had its API revamped and more functionality added, so I decided to give it a go. I believe it now expects hardware acceleration and has drivers for OpenGL and DirectX. Its appeal lies in its simplicity, good support, and is very cross platform, supporting Windows, Linux, OSX, iPhone, etc.

Build notes:

Dependencies

Previously I had been building libraries from their source and installing them in /usr/local using the usual UNIX build routine (i.e. download source and make). This is somewhat laborious and can be time consuming if something goes wrong (because not OSX compatible). This time round I decided to use MacPorts to do the lifting for me. This saves a lot of time. Just follow their standard installation instructions.

Then you need to install the libraries that you will need to compile Allegro 5. These are listed on this page, but aren't quite correct. I used:

sudo port install zlib freetype jpeg libogg libvorbis

Some of these need to be compiled in "universal" mode as they are compiled in 64 bit by default (which is the default of the compiler, new on OSX 10.6):

sudo port upgrade --enforce-variants libpng +universal

sudo port upgrade --enforce-variants physfs +universal

This will take a while if you are doing this from scratch (20+ mins). After this you should have a new /opt directory, which contains a load of new libraries. You can type "port installed" to see what you have. Some libraries will have "+universal" next to them.

Now download the Allegro 5 source, or get latest from svn. You can repeat the steps from here onwards when you get new versions of Allegro.

To build Allegro you can either build libraries or a framework, and you can either use makefiles or Xcode project files. I built libraries using Xcode 3, and now frameworks using makefiles. Frameworks are more in fitting with the Mac way of doing things, so probably best to use those.

Xcode 3 - Static library

To build using Xcode: Snow Leopard GCC compiles 64-bit code by default, but Allegro is not a 64-bit library, so we want to compile everything as i386. We first generate the Xcode files and then load them in Xcode 3 and change the settings for 32 bit (i386):

• cd to/allegro
• mkdir build
• cd build
• cmake -G Xcode ..

This will do a load of scanning for the dependencies it needs and then you'll end up with an Xcode project file: ALLEGRO.xcodeproj. This can be opened using Xcode 3 or 4. Although, at the current point (July 2011) I wouldn't recommend Xcode 4, it's just not ready.

For Xcode 3: open the the project file and (in the root project at the top):

• Change the Architectures to 32-bit Universal.
• I chose the RelWithDebInfo configuration. I haven't tried the others.
• Change the active architecture to i386. This is important as Allegro is 32-bit.
• Reading this article is useful if you don't know which SDK to use.

Build the ALL_BUILD target. You can run A5teroids and some of the example to check that it all works.

Sorry, I haven't built this using the project for Xcode 4. Use the frameworks below if you can't manage it. That's what I am using.

The install will fail because the script it is trying to run needs root access. So go back to the terminal and run the install command manually:

sudo cmake -DBUILD_TYPE=RelWithDbgInfo -P cmake_install.cmake

Then the Allegro files will be installed in /usr/local and you can include and link then from the usual places.

Frameworks

OSX 10.6 switched from 32 bit to 64 bit. Allegro needs to be compiled as 32 bit (i386). So we do the following in the unpacked allegro directory:

• mkdir build
• cd build
• cmake -DWANT_FRAMEWORKS=1 -DCMAKE_OSX_ARCHITECTURES=i386 ..
• make
• make install

And Bob is your Auntie.

Hopefully at some point some kind person will add Allegro 5 to MacPorts to save having to do this.

New Project

The easiest way to set a new project up is to create a command-line application in Xcode. However, if we want to package all the assets, like normal Mac applications, you need to create a Cocoa application ("New Project..." > "Cocoa Application").

In the project settings, add "/usr/local/include" as a user header path. This will include the Allegro file that we just installed above. In targets, right click on your application and choose "Add..." and add existing files "/usr/local/lib/liballegro.dylib" and "/usr/local/lib/liballegro_main.dylib". Now, you should be able to build and run your application. However, two windows will appear! This is because the liballegro_main stub will create a window as well as your default application having one (in the .xib).

To remove the default app window (because we want the Allegro one) look in the "resources" folder and open "MainMenu.xib". This brings up the interface designer. In the list of objects, delete the NSWindow object, this will stop two windows being created when the application starts. We also don't need the auto-generated stub code for the application either, so you delete the "main.m" and "app delegate.m" files. You can also delete items from the menu you don't want by dragging them onto the desktop (and they disappear in a puff of smoke). If you build and run you should have one window now.

There is a tutorial on Allegro 5 on the wiki. The API looks a bit more tidy and better namespaced now.


[6-Mar-11] - Updated for Allegro 5.0.0. Notes were previously for the release candidates.
[25-Mar-11] - Added missing libvorbis to port install.
[26-Apr-11] - Using Xcode 3 for building. Xcode 4 wasn't available when this was written.
[7-Jul-11] - Notes for building with frameworks and Macports 32-bit builds.