Installing Allegro 5 svn Using cmake

October 29, 2008
(Last updated February 19, 2009)

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.

Tutorial

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.

Congratulations! You have Allegro 5 installed! Now you can check out the examples directory to learn how to use various components of the library. Alternatively, you can read more of the tutorials found on this site. But first, I strongly recommend that you look at the documentation, as is discussed in the next section.

Documentation

While you can produce your own documentation from the source distribution, it may be easier to check them out online at http://docs.liballeg.org.

Note that I have not attempted to compile the documentation in Windows yet, so if you have notes on that process, please leave a comment. To generate Allegro 5's documentation, you will need the Pandoc program, located at http://pandoc.googlecode.com. This program in turn requires the Haskell compiler GHC, Cabal, and a slew of additional packages. Again, you may have better luck using the pre-generated documentation.

Gentoo has packages for ghc, cabal, parsec, network, and mtl, which I installed first, and were pre-requisites for CabalInstall, which I obtained from http://hackage.haskell.org/trac/hackage/wiki/CabalInstall, as was instructed in the INSTALL file for Pandoc. Using the Quick Installation on Unix instructions, I managed to install CabalInstall, which put a binary in ~/.cabal/bin. I added this to my path, as I was instructed to do:

	$ export PATH=$PATH:~/.cabal/bin

(Note that I have no idea what any of these things do, as I have not had the inclination to learn more about Haskell.) Next, I had to install a few more packages with cabal, as I was further instructed by the Pandoc installation notes.

	$ CABALOPTS=--global cabal update
	$ CABALOPTS=--global cabal install utf8-string zip-archive xhtml

Finally, we can install Pandoc. Enter Pandoc's directory and invoke make as I did:

	$ make
	$ make test
	$ make install

The test option is not required, but it feels good to see everything checking out as functional. With Pandoc finally installed, re-run cmake and make for Allegro, and you will have your docs.

Comments