Compiling Allegro 5 with Mac OS X Snow Leopard (10.6.6)

This tutorial takes you through building Allegro 5.0.0rc4 and compiling your first Allegro program. You will need the following:

• allegro-5.0.0rc4.tar.gz
• cmake (cmake-2.8.3-Darwin-universal.dmg)

The steps of the tutorial are as follows: 

1. Extract Allegro source files, and install CMake.
2. Use the CMake GUI to specify the Clang compiler, and to generate the makefile.
3. Run make and make install at the command-line.
4. Write and run your first Allegro 5 program.

Extract Allegro source and install CMake

1. Open Terminal.
2. cd ~/Downloads/
3. tar xvzf allegro-5.0.0rc4.tar.gz
4. cd allegro-5.0.0rc4.tar.gz
5. mkdir Build
6. cd Build
7. Double-click on the cmake .dmg file and install CMake.

The cd command, change directory, takes you inside the Downloads/ folder. The command tar with the x option specifies an extraction operation. (tar can also list, add or create compressed files.) The additional options v, z, f specify the following, respectively: 

• Show me what you're extracting.
• z because it's a gzip file. Notice the filename has a .gz extension.
• f because I'll supply you with the filename.

The Allegro README recommends building in a separate build directory, so we make the directory with mkdir. If you mess up during the build process, you just have to delete one folder; it's cleaner. We then go into the Build/ directory so that everything is built in this location. 

Installing CMake from a .dmg file should be self-explanatory.

Specify Clang as our compiler and generate the Makefile

1. Launch the CMake application from your Applications folder. 
2. In the Source field, enter /Users/your-login-name/Downloads/allegro-5.0.0rc4
3. In the Build field, enter /Users/your-login-name/Downloads/allegro-5.0.0rc4/Build
4. Click Generate - and when you do, a dialog like this should appear: 

If this dialog does not appear, make sure your Build/ directory is empty. This dialog needs to appear in order for you to specify Clang ("cee-lang") as your compiler of choice. It has to do with gcc being the default compiler and Snow Leopard being a 64-bit OS.

When this dialog appears, be sure to select "Specify native compilers." Clang comes with Snow Leopard; we just need to tell CMake that we will use Clang as our C compiler instead of the GNU C compiler. Click Continue. 

In the next dialog, in the C text field, enter the path to the clang tool: /Developer/usr/bin/clang

Click Done, and CMake should create nine files in the build directory. You can use ls to list them.

Make and make install

1. Still in the Build/ directory, type sudo cmake .
2. sudo make
3. sudo make install

Alright, now take a look at the /usr/local/lib directory. Note the pattern of each filename:

• lib
• allegro or allegro_something
• .dylib

Write and run your first Allegro program

1. Create a text file alleg5test.c and enter this code listing.
2. gcc alleg5test.c -o alleg5test -L/usr/local/lib -lallegro -lallegro_main
3. ./alleg5test

You should get a window with a black background to show up. If you did, congratulations!

Check out the pattern of the flags: a -l ("dash-el") followed by allegro_. I guess all of them are the .dylib files from /usr/local/lib. Hmm.

You might be able to adjust this tutorial to work with Xcode, and then to create an Allegro template. (Hint: See my previous tutorial on Flixel.)

I hope this saves you some time. Go through the tutorials, and go make some games!

References

• Dennis Sarrazin's post at 1:53 PM
• README.txt, README_macosx.txt, README_cmake.txt, etc.
• First Allegro 5 Tutorial

Updates

• 1/15/2011: Removed -lz option from the long gcc above. That would have told the linker to look for a library named "z." Lol.
• 1/15/2011: Much shorter gcc invocation. Originally gcc alleg5test.c -o alleg5test -lallegro -lallegro_font -lallegro_main -lallegro_primitives -lallegro_image -framework AppKit -framework OpenGL /usr/lib/libIOKit.dylib -framework Cocoa, but not all of these are needed (at least for our small program). Compare with Allegro 4.4, where you did gcc helloworld.c `allegro-config --libs`. The output of allegro-config 4.4.1 was -L/usr/local/lib -framework Cocoa -lalleg-main -lalleg. Similar, no? 
• 1/15/2011: I can't compile the bitmap tutorial at the Allegro wiki. My error message is, "Undefined symbols: _al_set_clear_to_color." Strange. Oops, typo. gg. There's a al_clear_to_color() function; I was just practicing my speed typing.
• 1/15/2011: Added an extra step, sudo cmake ., because there's no Makefile after CMake creates its nine files.
• 1/22/2011: Took out the "-framework Cocoa" switch in gcc. Don't need it.

Now, if only there was a allegro-config that could do for Allegro 5 what it did for Allegro 4.4. (If you're up to it, write a program allegro5-config that outputs the appropriate arguments to gcc, place it in /usr/local/bin, and then try gcc alleg5test.c `allegro5-config [--libs]`. It might not even have to be a program, but just a shell script.)

Passing code as a text stream into a program

A text stream is a line of text terminated by the newline character, '\n'. The standard library function getchar() retrieves one character at a time from the text stream. 


In the first chapter of Kernighan and Ritchie's The C Programming Language 2e, this function is used in programs of increasing complexity, from a character counter to a rudimentary syntax checker. 


Testing these programs in Xcode's Debugger Console can only be very limited. As soon as the user presses Enter, the text stream is happily processed, and the program expects additional input. But what if you want to test input spanning multiple lines?

In K&R C section 1.6, the first example program counts the frequency of different characters, like digits and blanks. Sample output is from "the program on itself." Near the end of the chapter, Exercise 1-23 asks to "write a program to remove all comments from a C program." There has to be some way to pre-populate the text stream, so that your program processes it to an EOF. 


Using cat, we can pipe the output of a file, such as main.c, to our program. Since we're using Xcode, the path to our project directory can be pretty long to type every time. Instead, we'll write an AppleScript script to tell Xcode to build the project, and to tell Terminal to activate and execute the cat pipe:

The script uses some parts from my previous AppleScript tutorial. Fortunately, all paths are POSIX formatted rather than aliases formatted as HFS paths.  


The one new thing is the use of quoted form, which lets me pass a directory with spaces, like /Programming Exercises/, without escaping the blanks.


With this script, the same program now processes a text stream all the way to EOF:

And the output:

I'm not sure how much use this will be beyond the first chapter, but now that I can pass text streams to EOF in my programs, I feel better about going through these exercises. Instead of one-liner "tests," I can pass whole files as representative input.


References

• Quoted form property of the text object, AppleScript Language Guide