This is a full featured native MacOS X port. The whole codebase is young, so it may hold some bugs; feedback is welcome!
MacOS X Allegro uses the current system keyboard mapping table to map scancodes to characters: the keyboard user settings in allegro.cfg have no effect. Allegro 4.4.2 build for OSX This is a build of Allegro 4.4.2 for Mac OS X (i386 arch). It's quite difficult to build this version of the library on modern systems due to the outdated dependencies it has. These instructions require the use of the OSX 10.4 SDK.
To build Allegro under MacOS X, you need:
- MacOS X 10.2.x or newer
- Apple Developer Tools (December 2002 or newer edition)
If you don't have the Developer Tools installed, you can get the latest release at:
On the same page you will also find instructions on how to install them. Note that system version 10.2.x is required to compile Allegro, but the library will still work on 10.1.x.
Allegro ships in source code form; this means you need to compile it before you can use it. You do this easily from a terminal window. Due to the multiplatform nature of the library, the first step is to fix it so it can be built under MacOS X, by running:
If you have checked out a development version from Allegro's CVS repository, run the following command. Otherwise, skip this step: Now Allegro is ready to be compiled. Start building it: And finally you install it (you need the root password for this step): Allegro has now been installed in your system as a standalone shared library, in /usr/local/lib. You may also wish to install the man pages: Alternatively, you can view the documentation in the Mac Help Center: You may also wish to install the library as a standard MacOS X framework: The 'Allegro' framework will be created into /Library/Frameworks. Note that the framework is standalone: it contains its own copy of the dynamic library, so it can be safely copied around. If you plan to embed the Allegro framework inside your application bundles, you must install a special embeddable version of it: Embedding the framework into your application bundles ensures they will work also on machines where Allegro is not installed. Note that if you embed the non-embeddable version of the framework into your app bundle, your program will not be able to load it and it will not work. Finally, if you plan on using Project Builder to code your apps, you may find useful installing an Allegro application PB project template: The dynamically linked version of the library gets built by default, but if you want to build a statically linked one, write the following on the command line: In the same manner we can also enter one of the following lines to build either the debug or the profiling version of the library: Then restart the build process by issuing: The static library will be installed in /usr/local/lib as the shared one, but you will not be able to install the framework nor the Project Builder template, which require a dynamically linked Allegro version.The options for linking with Allegro are quite long, expecially for static versions of the library as you need to pull in several different frameworks (Cocoa, QuickTime, etc.) other than Allegro itself. When linking against the shared library version, things are also different. To avoid you having to work out the right linker commands for yourself, the installation creates a script, allegro-config, that will print out a suitable commandline. You can use this inside a backtick command substitution, for example:
Or if you want to build a debug version of your program, assuming that you have installed the debug version of Allegro: You can also link against the Allegro framework, providing you previously installed it via make install-framework: Unix newbies, take note that these are ` backticks, not normal ' quotes!There are also switches for printing out the Allegro version number, overriding the install paths, and selecting between shared and static libraries, in case you installed both. Run allegro-config without any arguments for a full list of options.
If you get an error like 'allegro-config: program not found', and you're sure you have built and installed the library as described above, it probably means that /usr/local/bin is not on your path. The method to add it depends on the shell you're using. If you have tcsh, add the following line to the end of the .cshrc in your home directory.
If you have bash, add the following line to the end of the .bash_profile file in your home directory: If you don't know which, just type echo $SHELL on the command line, which will print either /bin/bash or /bin/tcsh. Newer versions of OSX use bash, older ones use tcsh. You will have to close the Terminal window and open a new one once you have made the changes, so it will have an effect.To use Allegro from inside Apple's Project Builder, be sure you first installed the library as a framework and that you also installed the PB application template (see section 'Installing Allegro' for details).
Once you're ready, start up Project Builder and choose 'New Project' from the 'File' menu. On the very first dialog, you'll be prompted with a list of project templates with which to create your program. Select 'Allegro Application' under the 'Application' category and enter the project name and location in the next dialog. Once the setup is complete, you will find yourself with an opened Allegro application project, holding an unique source file (main.c) and some linked frameworks. The project can already be compiled to a working application; try it!
Note that the same procedure applies to XCode, which is compatible with Project Builder.
The main.c source file contains a very simple skeleton of an Allegro program that will open up a white window with the text 'Hello, world!' in the center. This file is just a start: you can (and should) completely replace its contents to suit your needs.
When you build applications from the command line, you're actually just creating the executable, so you can run it from the command line only, and not also from the finder like a common MacOS X application. In other words, compiling from the command line does not create application bundles.
Allegro ships with a little tool, named fixbundle, which allows to build an application bundle out of an executable. The utility works from the command line and it accepts a variety of options to customize your bundle; the easiest way to use it is:
This will create an application bundle named 'executable_name.app' that contains your program executable and will appear in the finder with the default application icon. A more complex usage example follows: This creates a bundle named 'bundle_name.app'. The executable will be moved instead of copied into the bundle; the application will be marked as version '1.2' and icon.bmp will be converted to an icon for the bundle. You can specify more options and up to 4 differently sized icons (16x16, 32x32, 48x48 and 128x128) to be read from any Allegro supported image files or from datafile objects. Run fixbundle without arguments for the full list of known options.A special note is required for the '-e' switch; this lets you embed the Allegro framework inside the built application bundle, so your app will not require Allegro to be installed into the target machine in order to work. This flag assumes you previously installed the embeddable version of the Allegro framework, and that your executable has been linked to it, either via Project Builder or XCode, either via the allegro-config script. If one of these conditions is not met, the created app may not work on target machines.
Bundles created by fixbundle have this default layout:
If you are using Project Builder to compile your programs, there is no need to use fixbundle, as the IDE will do the work of generating an application bundle for you.When an Allegro program starts, it automatically detects if the executable lives inside a bundle or not. The working directory is always set up to be the directory where the standalone executable or application bundle is located, but there is an exception: if the application is a bundle and Allegro finds a directory under the bundle Contents/Resources path with the same name of the executable (note that here we mean the real executable name, not the bundle name), that directory is set to be the working one. This allows to easily package all the application data inside the bundle, and still have a working program without the need to tell your code about the changed location of your files.
This section contains MacOS X-specific notes on the drivers available.
MacOS X Allegro uses the current system keyboard mapping table to map scancodes to characters: the keyboard user settings in allegro.cfg have no effect. Allegro 4.4.2 build for OSX This is a build of Allegro 4.4.2 for Mac OS X (i386 arch). It's quite difficult to build this version of the library on modern systems due to the outdated dependencies it has. These instructions require the use of the OSX 10.4 SDK.
To build Allegro under MacOS X, you need:
- MacOS X 10.2.x or newer
- Apple Developer Tools (December 2002 or newer edition)
If you don't have the Developer Tools installed, you can get the latest release at:
On the same page you will also find instructions on how to install them. Note that system version 10.2.x is required to compile Allegro, but the library will still work on 10.1.x.
Allegro ships in source code form; this means you need to compile it before you can use it. You do this easily from a terminal window. Due to the multiplatform nature of the library, the first step is to fix it so it can be built under MacOS X, by running:
If you have checked out a development version from Allegro's CVS repository, run the following command. Otherwise, skip this step: Now Allegro is ready to be compiled. Start building it: And finally you install it (you need the root password for this step): Allegro has now been installed in your system as a standalone shared library, in /usr/local/lib. You may also wish to install the man pages: Alternatively, you can view the documentation in the Mac Help Center: You may also wish to install the library as a standard MacOS X framework: The 'Allegro' framework will be created into /Library/Frameworks. Note that the framework is standalone: it contains its own copy of the dynamic library, so it can be safely copied around. If you plan to embed the Allegro framework inside your application bundles, you must install a special embeddable version of it: Embedding the framework into your application bundles ensures they will work also on machines where Allegro is not installed. Note that if you embed the non-embeddable version of the framework into your app bundle, your program will not be able to load it and it will not work. Finally, if you plan on using Project Builder to code your apps, you may find useful installing an Allegro application PB project template: The dynamically linked version of the library gets built by default, but if you want to build a statically linked one, write the following on the command line: In the same manner we can also enter one of the following lines to build either the debug or the profiling version of the library: Then restart the build process by issuing: The static library will be installed in /usr/local/lib as the shared one, but you will not be able to install the framework nor the Project Builder template, which require a dynamically linked Allegro version.The options for linking with Allegro are quite long, expecially for static versions of the library as you need to pull in several different frameworks (Cocoa, QuickTime, etc.) other than Allegro itself. When linking against the shared library version, things are also different. To avoid you having to work out the right linker commands for yourself, the installation creates a script, allegro-config, that will print out a suitable commandline. You can use this inside a backtick command substitution, for example:
Or if you want to build a debug version of your program, assuming that you have installed the debug version of Allegro: You can also link against the Allegro framework, providing you previously installed it via make install-framework: Unix newbies, take note that these are ` backticks, not normal ' quotes!There are also switches for printing out the Allegro version number, overriding the install paths, and selecting between shared and static libraries, in case you installed both. Run allegro-config without any arguments for a full list of options.
If you get an error like 'allegro-config: program not found', and you're sure you have built and installed the library as described above, it probably means that /usr/local/bin is not on your path. The method to add it depends on the shell you're using. If you have tcsh, add the following line to the end of the .cshrc in your home directory.
If you have bash, add the following line to the end of the .bash_profile file in your home directory: If you don't know which, just type echo $SHELL on the command line, which will print either /bin/bash or /bin/tcsh. Newer versions of OSX use bash, older ones use tcsh. You will have to close the Terminal window and open a new one once you have made the changes, so it will have an effect.To use Allegro from inside Apple's Project Builder, be sure you first installed the library as a framework and that you also installed the PB application template (see section 'Installing Allegro' for details).
Once you're ready, start up Project Builder and choose 'New Project' from the 'File' menu. On the very first dialog, you'll be prompted with a list of project templates with which to create your program. Select 'Allegro Application' under the 'Application' category and enter the project name and location in the next dialog. Once the setup is complete, you will find yourself with an opened Allegro application project, holding an unique source file (main.c) and some linked frameworks. The project can already be compiled to a working application; try it!
Note that the same procedure applies to XCode, which is compatible with Project Builder.
The main.c source file contains a very simple skeleton of an Allegro program that will open up a white window with the text 'Hello, world!' in the center. This file is just a start: you can (and should) completely replace its contents to suit your needs.
When you build applications from the command line, you're actually just creating the executable, so you can run it from the command line only, and not also from the finder like a common MacOS X application. In other words, compiling from the command line does not create application bundles.
Allegro ships with a little tool, named fixbundle, which allows to build an application bundle out of an executable. The utility works from the command line and it accepts a variety of options to customize your bundle; the easiest way to use it is:
This will create an application bundle named 'executable_name.app' that contains your program executable and will appear in the finder with the default application icon. A more complex usage example follows: This creates a bundle named 'bundle_name.app'. The executable will be moved instead of copied into the bundle; the application will be marked as version '1.2' and icon.bmp will be converted to an icon for the bundle. You can specify more options and up to 4 differently sized icons (16x16, 32x32, 48x48 and 128x128) to be read from any Allegro supported image files or from datafile objects. Run fixbundle without arguments for the full list of known options.A special note is required for the '-e' switch; this lets you embed the Allegro framework inside the built application bundle, so your app will not require Allegro to be installed into the target machine in order to work. This flag assumes you previously installed the embeddable version of the Allegro framework, and that your executable has been linked to it, either via Project Builder or XCode, either via the allegro-config script. If one of these conditions is not met, the created app may not work on target machines.
Bundles created by fixbundle have this default layout:
If you are using Project Builder to compile your programs, there is no need to use fixbundle, as the IDE will do the work of generating an application bundle for you.When an Allegro program starts, it automatically detects if the executable lives inside a bundle or not. The working directory is always set up to be the directory where the standalone executable or application bundle is located, but there is an exception: if the application is a bundle and Allegro finds a directory under the bundle Contents/Resources path with the same name of the executable (note that here we mean the real executable name, not the bundle name), that directory is set to be the working one. This allows to easily package all the application data inside the bundle, and still have a working program without the need to tell your code about the changed location of your files.
This section contains MacOS X-specific notes on the drivers available.
Display switching is possible, but only the SWITCH_BACKGROUND mode is supported, so your application will have to deal with it.
Fullscreen mode uses the CoreGraphics DirectDisplay API; only 8, 15 and 32 bit color depths are supported.
Allegory Masque Of The Red Death
Fable Mac Osx
On MacOS X 10.1.x, mouse autodetection is not possible, and Allegro will assume an 1-button mouse to always be present, activating buttons emulation accordingly.
Allegory Masterclass
There is a known compatibility problem when using gcc 4 on MacOS X 10.4 that prevents binaries from working on older versions of MacOS X. While it is anticipated that a future update from Apple will fix this problem, you can use gcc 3 to work around it.
As a final note, when coding Allegro programs don't forget that you need to use the END_OF_MAIN() macro right after your main() function!
