Starting with Xcode

You can use Xcode on macOS to write Allegro programs, but there is a bit of setting up to do first. Xcode helps with auto-completion, has decent project management (e.g. jump to definition) and integrates well with the debugger. However it is rather heavyweight and quirky if you are used to another IDE. This page covers getting started with a minimal project. Making a bundle which can be deployed to another Mac is described on another page.

Prerequisites

• Allegro installed via homebrew
• pkg-config also installed via homebrew
• Xcode (these screenshots show Xcode 12)

Step 1 - create a new project

Use the 'Welcome Screen' or the File | New menu to create a new Command Line tool project.

Choose C or C++ as the language. Save this where you want.

Step 2 - find out where homebrew put the Allegro files

The easiest way is via a Terminal window. Open a terminal and type:

pkg-config --variable=includedir allegro-5

and you will see a response showing where the Allegro include files are stored, which will look something like

/usr/local/Cellar/allegro/5.2.7.0/include

Likewise, find the libraries with:

pkg-config --variable=libdir allegro-5

Step 3 - put these locations into your project

Go to the target settings in Xcode, and look for the section called 'Search Paths'. Make sure you've selected 'All' near the top. Edit the 'Header Search Paths' to add the location of the include files that came from pkg-config. You can also fill in the 'Library Search Paths' but it isn't necessary at this point

Step 4 - add the libraries

The easiest way is to open a Finder window on the directory that you got from pkg-config, and drag the Allegro libraries onto the Frameworks and Libraries section of the Target's General Settings page. Alternatively press the plus button and navigate to them. You will need at least liballegro.dylib and liballegro_main.dylib. If you are using addons you will need to add their libraries too, for example if using the Image addon, drag in liballegro_image.dylib

Step 5 - edit some code

Xcode adds a main.c or main.cpp file to start, you can edit this to bring in the Allegro include file, then get started. Code completion should be working at this point.

#include <allegro5/allegro.h>

int main(int argc, const char * argv[]) {
  al_init();
  al_create_display(320, 240);
  al_rest(10.0);
  return 0;
}

Step 6 - sort out code signing

If you try to build the program at this point you will get code signing errors. Go back to the settings and find the target's Signing section on the General settings page (note, it's not the 'Signing and Capabilities' page). Where it says 'Code Signing Identity', click on the text that reads 'Apple Development', select Other... and just blank out any text that appears in the box. This will disable code signing requirements. Note that when you come to deploy your app to the Apple Store you'll need to do signing for real, but it's better to deal with that when the need arises.

Step 7 - sort out C++

The project will now build but, if you're using C++, it won't run.

The problem is Allegro's 'magic main' function needs main to be int main(int argc, char * argv[]) and Xcode's template starter file has int main(int argc, const char * argv[]). In C++ the name mangling means that those functions are different. Simply delete the const from the declaration.

Step 8 - run the program

It should now be possible to start developing and debugging an Allegro program.