Allegro 5 Tutorial
Installing Allegro 5 Using cmake
October 29, 2008
(Last updated November 2, 2008)
Abstract
In this tutorial, we will learn how to go from nothing to a full installation of the most up-to-date version of the Allegro 5 library. This tutorial is geared towards either Windows or Linux users who use gcc as their compiler (MinGW in Windows). It may serve as a guide for other platforms and compilers, but has not been tested. You may have better luck reading the readme file included with Allegro 5.
Before we can begin, we must have two external programs: Subversion and cmake. Note also that we will need cmake version 2.6 or greater, or it will not work.
Linux users: You probably have a package manager which will install these for you. Being a Gentoo Linux user myself, I had to type the following command as root to get the packages installed:
# emerge subversion cmake
Your package manager may be different. For example, Red Hat has a graphical one, and I have no idea what Ubuntu uses. If you can't figure it out, use Google to find information about your specific distribution.
Windows users: You will want to install these programs yourself. I suggest using the Windows binaries provided on the respective web sites. For Subversion, I downloaded the CollabNet "Certified Binary", which unfortunately requires a (free) registration to download. I sped by this limitation by using the spiffy bugmenot website.
The installer for cmake will offer to set up the system path for you, which is convenient. Unfortunately, the Subversion one will not, so you need to make note of where that program is installed to. As of the writing of this tutorial, it defaults to "C:\Program Files\CollabNet Subversion". You will want to add this to your path in a moment.
Once Subversion and cmake are both installed, open a console and make sure that you can find them. Click Start->Run->"cmd" and press Enter. A DOS-like box should open up. For the rest of this and future tutorials, I will assume that you know how to use this environment. Now first set the path for Subversion, and test that both programs work:
> path=%path%;"C:\Program Files\CollabNet Subversion" > svn --version > cmake --version
If either of these programs is not found, then you have installed it improperly, and cannot continue.
Installing for Windows has one more prerequesit: DirectX libraries and headers. Previous versions of Allegro required just DirectX 7 libraries and headers. If that is all you installed, you do not have enough. You will need the ones for DirectX 9 as well. Trent Gamblin has graciously provided a small package for you to use: DirectX 9 for MinGW. Copy the "include" and "lib" directories to your MinGW installation and you're good to go.
All users: Next thing we want to do is obtain the latest version of the library. Open a console. Due to a limitation with the Unix version of subversion, you cannot use a FAT32 partition to get the latest version. (While I have not tested it, I assume it will be okay with the Windows version.) Create a new directory, you may call it whatever you like. I have called it "allegro-svn" on my computer.
mkdir allegro-svn cd allegro-svn
From within this directory, type the following subversion command:
svn co https://alleg.svn.sourceforge.net/svnroot/alleg/allegro/branches/4.9
(This command is really just a long URL. The "co" stands for "check out" and the URL is the location of the subversion repository.) You should see a bunch of lines scrolling on the screen of all the files it is downloading. If this is not your first time running the command, it will update your files so they match the latest version. If you want to stay up-to-date on the latest version of the library, it is a good idea to run this command every day and recompile. Be warned, however, that sometimes the latest version will be broken and may not work at all. In fact, the version you have just downloaded may be one which was broken. It never hurts to tell someone if this is the case.
By the time you've gotten to this paragraph, and assuming that you have a relatively speedy Internet connection, you should be done downloading the library. You'll notice there is now a new directory titled "4.9". Enter it.
cd 4.9
Windows users: when downloading the svn of Allegro 5, you need to regenerate the library definitions. This is done by typing the following command when in the 4.9 directory:
> misc\fixdll
All users:This is where things will begin to get different. To use cmake, we will want to first create a new directory in here titled "Build", and then enter it:
mkdir Build cd Build
Using cmake isn't as hard as I previously thought it was. You just have to type a simple command, with flags to denote which versions of the library to compile. The flags are listed below:
Flag Description Default value =========================================================== -DGRADE_STANDARD Build release library on -DGRADE_DEBUG Build debug library off -DGRADE_PROFILE Build profiling library off -DSHARED Build shared libraries on -DSTATIC Build static libraries on
This list was extracted from Allegro's readme file (readme-a5.txt). Suppose you wanted to install the release, debug, and static libraries, but not shared or profiling. You would use the following command:
Linux users:
$ cmake .. -DGRADE_DEBUG=on -DSHARED=off
Windows users:
> cmake .. -G "MinGW Makefiles" -DGRADE_DEBUG=on -DSHARED=off
All users: The ".." at the beginning is telling cmake where the definition file is: in the parent directory. (In case you're curious, the file it looks at is titled "CMakeLists.txt".) Note how I did not worry about the other options because their default values were exactly what I wanted. You can change this line to suit your needs. Since I like to assist in development of the library, I always compile with the debug version. If in doubt about whether you need an option or not, stick with the default one.
Some more text will fly over the screen, but this can probably be disregarded, unless there is an error message printed at the end. This is the configure step -- you'll notice it goes much faster than the traditional script. I've never had a problem with this step myself. You may want to check to verify that it was able to locate certain libraries, such as libpng and freetype.
That's it with the unfamiliar stuff. Now we can execute those classic lines to compile and install.
Linux users:
$ make $ make install
Note that you may need to be root for the installation step.
Windows users:
> mingw32-make > mingw32-make install
It's pretty silly, but currently the Allegro .dll files are installed to the "lib" directory for your compiler. You'll want to manually move these to the "System32" directory of your Windows installation. You may also want to keep a copy somewhere easily locatable, so that if you are packaging an installer for your latest game, you don't have to go searching. ("What was that .dll called again..?")
All users: You'll notice that the makefile output is much prettier than "standard" makefiles. Once you have everything installed, you should be ready to give the next tutorial a try. Or, you can continue and find out how to generate the documentation.
Documentation
All of Allegro 5's documentation is embedded in the source files. Various elements are given specially formatted comments, which can then be extracted. The developers have chosen to use the Natural Docs format. The installation is rather straightforward for Linux. If you are running Windows, you will first need to install Perl. Instructions for doing so are included on the Natural Docs web site. Natural Docs itself is just a Perl script, so downloading and installing in Linux is as easy as extracting and making a symlink to your /usr/bin directory. In Windows, sorry, I've not yet gotten a chance to try it. It should be relatively easy though.
Note that to generate the docs for Allegro 5, you must have Natural Docs 1.4 or greater! Using an older version will not work, and will confuse and anger you. At the time of this writing, the latest version that Gentoo Linux knows about is 1.35. This is not sufficient. You will get errors. Instead you must install the script manually from their web site.
To generate Allegro 5's documentation, enter the "docs/naturaldocs" directory of your copy of the source, and type "make". If everything went well, you now have all the documentation right there. The index file is docs/naturaldocs/public/html/index.html.