Before you can start using Allegro, you must install the Allegro support files in your compiler's folder. Let's start with where to find the Allegro support files. On the CD-ROM in the Allegro 4.2 folder is a file called allegro-msvc6-4.2.0.zip. This zip file has been opened and is located in the Allegro 4.2 folder already. Inside this folder you will find three sub-folders:

The lib and include folders need to be copied into the Visual C++ 6.0 installation folder on your hard drive. This is usually located at C:Program FilesMicrosoft Visual StudioVC98. Just copy both folders into this location, and then you will be able to create Allegro projects very easily. (When warned that the folders already exist, go ahead and proceed, nothing will be overwritten.)

The third folder, bin, contains the Allegro library DLLs, which must be distributed with your Allegro programs. The DLLs contain the compiled Allegro library. When your program includes the allegro.h header file, it refers to function names stored in the library file (such as alleg.lib). This library file does not actually contain the Allegro functions, it just includes a link to the DLL file (such as alleg42.dll).

So, let's summarize. You write a C++ program that includes the allegro.h header file. You add alleg.lib to your project's linker settings so that it is compiled within your executable file. That code points to an external DLL called alleg42.dll. When your game first loads up, it also loads the DLL into memory. Any Allegro function that your game calls jumps over to the DLL code in memory and executes.

This is called the dynamic link method. There is also a way to compile the entire Allegro library so that it is linked into your executable file, and then there is no need for the DLL—this is called the static link method. You can see the statically linked library files inside the lib folder that you just copied into Visual C++ 6.0. If you look inside, you'll see six library files:

Don't let these files confuse you, because their names tell us what they are all about, and you just need it to be explained to you. The standard library file is called alleg.lib. This is used in a normal “Release” type build of your game. All C++ compilers support multiple configurations, so you can use Debug mode when developing and testing the code, and then switch to Release mode for when your game is ready to go. The debug configuration produces slower code than release mode, because it includes variable names and line numbers and other things that make debugging possible. The release version of an executable leaves all of that stuff out so the code will run faster.

The last step is to copy the DLL files out of the bin folder to C:Windows System32. On some systems, this might be C:WINNTSystem32. You will need to copy these three files:

alleg42.dll

alld42.dll

allp42.dll

Copying these files to your system folder will make it possible to run any Allegro program from anywhere on your hard drive without having to deal with the error message that the DLL is not found. The alternative is to always copy the appropriate DLL file to your project folder. You just have to remember that the DLL has to be distributed with your game too! So, keep a copy of the DLL file you're using handy for when you want to send your game to a friend.

Try not to be confused by all the different files we've looked at here. You really only deal with one type of file at a time, depending on the configuration of your compiler. If you are in the middle of developing a game, you'll want to use Debug mode, but when the game is finished and ready for release, you can switch to Release build and recompile your project. If you want to keep things simple, you can just use alleg.lib all the time. This is the release version of the library. Odds are, you will never need to debug into the Allegro library, so I see nothing wrong with just using alleg.lib all the time (thus ignoring alld.lib). It is certainly faster to use the release version of the library.

Here is how you can configure a Visual C++ 6.0 project to use the Allegro library. First, fire up Visual C++ 6.0, if you don't have it open yet. Next, create a new Win32 Application type project (see Figure 2.1) by selecting File, New. Give the project any name you want.

Figure 2.1. The New Project dialog box in Visual C++ 6.0.

Next, open the Project menu and select Settings to bring up the Project Settings dialog (see Figure 2.2). Click on the Link tab at the top and look for the Object/Library Modules text field. Clear the entire field and type in alleg.lib in place of the other library files, as shown in the figure. All you need for a dynamically linked Allegro program is the alleg.lib library file.

Figure 2.2. The Project Settings dialog box in Visual C++ 6.0.

Now you need to make sure the linker can find Allegro. Add a new source code file to the project and type in the following code. This program does very little, but it verifies that Allegro has been linked to your program.

#include <allegro.h>
int main(void) {
    allegro_init();
    set_gfx_mode(GFX_SAFE, 640, 480, 0, 0);
    install_keyboard();
    textout_ex(screen, font, "Hello World!", 1, 1, 10, -1);
    textout_ex(screen, font, "Press ESCape to quit.", 1, 12, 11, -1);
    while(!key[KEY_ESC]);
    allegro_exit();
    return 0;
}
END_OF_MAIN()

If all goes as expected, the compilation output window should show “0 error(s), 0 warning(s)” (see Figure 2.3), and upon running the program, you should see a message box with the phrase “Welcome To Allegro!” If there are any errors, be sure to check for typos.

Figure 2.3. Compiling an Allegro program with Visual C++ 6.0.

To statically link the Allegro library with your program's executable, you must have the DirectX SDK (Software Development Kit) installed. The DirectX SDK is installed to the lib and include folder in your compiler's folder, just like the Allegro files. When you link dynamically, Allegro's functions only need the DirectX runtime, so there's no extra files needed. But when you compile the static library, it must make calls into DirectX for drawing surfaces and sprites and playing sound effects and so on.

Although DirectX 9 is available at the time of this writing, you really only need DirectX 8 to compile statically linked code with Allegro. But, you will only need to install the DirectX SDK (which includes the header and library files) if you want to compile the static version of Allegro. If you have not already installed it, refer to the CD-ROM folder called DirectX. If you are using the dynamic version of Allegro (which is most likely the case), you will not need the DirectX SDK. This is an option for advanced users. All you need for normal dynamically linked Allegro programs is the normal DirectX runtime that is most likely already installed on your system. As far as other operating systems are concerned, there are no special libraries or SDKs needed.

Now let's look at how to configure a Visual C++ 6.0 project to build a program using the static Allegro library. This type of project needs a lot more library files than the single alleg.lib file you configured before. Open up the Project Properties and look in the linker object/library modules text box, and add the following entries. Be sure to separate each one with a space.

alleg_s.lib
gdi32.lib
winmm.lib
ole32.lib
dxguid.lib
dinput.lib
ddraw.lib
dsound.lib

The DirectX-specific library files are dxguid.lib, dinput.lib, ddraw.lib, and dsound.lib. The Windows version of Allegro specifically calls on various DirectX functions to get things done when you call on Allegro-specific functions. On other platforms, like Mac and Linux, there are different libraries used. DirectX is only required on the Windows platform.

There is one more option that needs to be set. You need to tell Allegro to use the static library by including the following line at the top of any program that will use the static library:

#define ALLEGRO_STATICLINK

I have provided a static link project template for Visual C++ 6.0 in the sourcesmsvc60chapter02 folder on the CD-ROM for your use. I won't be going over the steps to create a static project for every compiler, but I have provided examples for you on the CD-ROM.

Now let's try out the installation by creating a test project, and then see if we can build some Allegro code to verify it is working. Open up Visual C++ and create a new Win32 Project. To do this, open the File menu and choose New, Project, as shown in Figure 2.4. Choose a folder where the new project will be located and enter a name for your new project. I have called this program TestAllegro but you may give it any name you want.

Figure 2.4. Creating a new Win32 Project in Visual C++ .NET.

Next, you'll see the Application Wizard dialog box come up, as shown in Figure 2.5. Click the Application Settings option on the left (below the Overview tab). We don't want a project full of template files, so just check the Empty Project checkbox. Make sure under the Application type list you have Windows application selected. Click Finish, and the project will then be created, as shown in Figure 2.6. But this is an empty project, because you chose that option.

Figure 2.5. The Application Wizard in Visual C++ .NET.

Figure 2.6. The new project has been created in Visual C++ .NET.

Now let's add a source code file to the project. Open the Project menu, and select Add New Item as shown in Figure 2.7. This will bring up the Add New Item dialog box. In the list of templates on the right, choose the C++ File (.cpp) template. Down below, in the Name field, name this new file main.cpp, as shown in Figure 2.8.

Figure 2.7. Adding a new source code file from the Project menu.

Figure 2.8. The Add New Item dialog box.

You will now see that the new file has been added to the project. The source code file, main.cpp, is currently empty, as you can see in Figure 2.9. Let's type some code into this file. The following code listing might not make much sense to you since we haven't studied any Allegro code yet, so bear with me at this point and I will explain the code very soon. All we want to do right now is get the compiler configured properly.

Figure 2.9. The new main.cpp source code file has been added to the project.

#include <allegro.h>
int main(void) {
    allegro_init();
    set_gfx_mode(GFX_SAFE, 640, 480, 0, 0);
    install_keyboard();
    textout_ex(screen, font, "Hello World!", 1, 1, 10, -1);
    textout_ex(screen, font, "Press ESCape to quit.", 1, 12, 11, -1);
    while(!key[KEY_ESC]);
    allegro_exit();
    return 0;
}
END_OF_MAIN()

Now you can configure the project so that all of those Allegro functions will actually compile and run. If you just try to run the project right now, you'll get compiler or linker errors. Let's open the project's Properties dialog box so you can configure it. Open the Project menu, as shown in Figure 2.10, and select the TestAllegro Properties option at the bottom of the menu.

Figure 2.10. The Project menu.

This will bring up the property pages for your project. Select the C/C++ item on the tree to the left. Click on the Code Generation item under C/C++ options, as shown in Figure 2.11. Then click on the Runtime Library option. Using the drop-down list, change the runtime library to Multi-threaded Debug DLL as shown. The reason why this change is needed is that Visual C++ creates a single-threaded project by default, and Allegro is a multi-threaded library. So, in order to use Allegro, we have to make sure the compiler will output multi-threaded code.

Figure 2.11. The Code Generation property page.

Now we have to make another change while we're in this Properties dialog. The next item down in the tree below C/C++ is called Linker. Open up this property page. Then click on the Input item in the Linker list to bring up the linker dependencies page shown in Figure 2.12. This is where you tell the compiler to use the Allegro library file. In the Additional Dependencies textbox, type in alleg.lib.

Figure 2.12. The Linker property page.

Your project is now configured. Go ahead and build the code to verify that it is working properly. Also, make sure the Allegro DLL files are available, either in the Windows system32 folder or in your project folder. If the configuration was set up properly, you should see the window shown in Figure 2.13 appear on the screen. If you get any errors, go back and double-check the steps in this tutorial to see if you have made a typo or missed a step. Since there are really only a few steps involved, you should be able to narrow down any problem.

Figure 2.13. The TestAllegro program.

Now let's try out the installation by creating a test project, and then see if we can build some Allegro code to verify it is working. Open up Visual C++ 2005 and create a new Empty Project. To do this, open the File menu and choose New, Project, as shown in Figure 2.14. Choose a folder where the new project will be located and enter a name for your new project. I have called this program TestAllegro but you may give it any name you want. Note that I have selected Empty Project from the list of project templates in Figure 2.15. This figure is from the Express Edition, and will look a little different if you are using the Professional edition.

Figure 2.14. Opening the New Project dialog from the File menu.

Figure 2.15. The New Project dialog.

This process will be a little different than the process for Visual C++ 2003, because there is no Application Wizard this time. Instead, the new project is simply created and ready for you to add a new source code file (see Figure 2.16).

Figure 2.16. A new project has been created in Visual C++ 2005.

Now let's add a source code file to the project. Open the Project menu, and select Add New Item to bring up the Add New Item dialog box. In the list of templates on the right, choose the C++ File (.cpp) template. Down below, in the Name field, name this new file main.cpp, as shown in Figure 2.17.

Figure 2.17. Adding a new source code file to the empty project.

You will now see that the new file has been added to the project. The source code file, main.cpp, is currently empty. Let's type some code into this file. The following code listing might not make much sense to you since we haven't studied any Allegro code yet, so bear with me at this point and I will explain the code very soon. All we want to do right now is get the compiler configured properly.

#include <allegro.h>
int main(void) {
    allegro_init();
    set_gfx_mode(GFX_SAFE, 640, 480, 0, 0);
    install_keyboard();
    textout_ex(screen, font, "Hello World!", 1, 1, 10, -1);
    textout_ex(screen, font, "Press ESCape to quit.", 1, 12, 11, -1);
    while(! key[KEY_ESC]);
    allegro_exit();
    return 0;
}
END_OF_MAIN()

When you have typed the code in, the IDE should look like Figure 2.18. If you have any experience with C++, you are probably mystified by that unusual function called at the end of the main function, called END_OF_MAIN(). Note also that there is no semicolon after this line. That's not actually a function call at all, it's a macro used by Allegro to identify the end of the main function. In normal Windows programming, the main function is called winmain() instead of just plain main(). Allegro doesn't like this, because C++ programs in all other platforms just use main(). Windows is kind of an oddball in this respect, which is why END_OF_MAIN() is needed. You'll get used to it as a trademark of an Allegro program soon enough.

Figure 2.18. The Allegro program is almost ready to be tested.

Now you can configure the project so that all of those Allegro functions will actually compile and run. If you just try to run the project right now, you'll get compiler or linker errors. Let's open up the project's Properties dialog box so you can configure it. You'll find that this is even easier than the configuration for Visual C++ 2003, if you read that section of the chapter. Open the Project menu and select the Properties option at the bottom of the menu.

This will bring up the property pages for your project. We don't need to set the code generation to multi-threaded, which was necessary with 2003, because 2005 uses this option by default! See, I told you things were easier with this compiler. Now we have to simply add one small item to the properties for this project, and then it will compile the Allegro code. Look at the list of Configuration Properties on the left. Open up the property page called Linker. Then click on the Input item in the Linker list to bring up the linker dependencies page shown in Figure 2.19.

Figure 2.19. Adding the Allegro library as a linker input option.

This is where you tell the compiler to use the Allegro library file. In the Additional Dependencies textbox, type in “alleg.lib”.

Your project is now configured. Go ahead and build the code to verify that it is working properly by pressing Ctrl+F5 (pressing just F5 runs the program with debugging, which is slower, but you may do that if you want). Also, make sure the Allegro DLL files are available, either in the Windows system32 folder or in your project folder.

If the configuration was set up properly, you should see the window come up with the message “Hello World!” on it (shown previously in Figure 2.13). If you get any errors, go back and double-check the steps in this tutorial to see if you have made a typo or missed a step. I have performed this new project configuration dozens of times, and it really is a cinch, so if there is an error, it's always due to a missing library file. Did you copy all of the lib and include files as explained earlier? That is really all there is to it, and this compiler works great for compiling Allegro programs!

First, let's fire up Dev-C++ and create a new project. Open the File menu and select New, Project, as shown in Figure 2.21. Select Empty Project and give it an appropriate name. I have called this project Test_DevCpp, which is what it is called on the CD-ROM. Dev-C++ will ask you where you would like to save the new project. Choose a folder on your hard drive where you would like to save the new project.

Figure 2.21. Opening the New Project dialog in Dev-C++.

Now that the new project has been created, you need to add a new source code file to the project. Open the Project menu and select New File (see Figure 2.22).

Figure 2.22. The New Project dialog in Dev-C++.

Dev-C++ will immediately open a new file in the code editor. Open the File menu and choose Save to save the new source code file as main.cpp. Now type in the source code that follows for this test program:

#include <allegro.h>
int main(void) {
    allegro_init();
    set_gfx_mode(GFX_SAFE, 640, 480, 0, 0);
    install_keyboard();
    textout_ex(screen, font, "Hello World!", 1, 1, 10, -1);
    textout_ex(screen, font, "Press ESCape to quit.", 1, 12, 11, -1);
    while(!key[KEY_ESC]);
    allegro_exit();
    return 0;
}
END_OF_MAIN()

When you have typed in the code, the Dev-C++ IDE will look like Figure 2.23.

Figure 2.23. Typing in the source code for a test program in Dev-C++.

Now let's configure the project so it will compile Allegro code. If you try to compile the program right now, it will generate errors because you haven't told the compiler where to find the Allegro library file. So, let's do that. It's very easy, but quite different from the other compilers we've looked at so far. If you open the Project menu, you'll find an option called Project Options. This brings up the Project Options dialog box, shown in Figure 2.24 .

Figure 2.24. Changing the project options in Dev-C++.

The first thing you should do in the Project Options dialog is change the project type. When you create an empty project, Dev-C++ defaults to Win32 Console. Change it to Win32 GUI. This will get rid of a pesky pop-up window every time you run an Allegro program from Dev-C++. Setting it to Win32 GUI will cause just a single window to appear when you run your code.

Now there's just one thing we need to add to configure the project to support the Allegro library. In the Project Options dialog, click on the Parameters tab on the top. There are three types of parameters you can set in this tab: Compiler, C++ Compiler, and Linker. In the Linker field, add “–lalleg” as shown in Figure 2.25. Click OK to close the dialog.

Figure 2.25. Adding the Allegro library to the linker options.

The project is now ready to be compiled and run. In Dev-C++, you use the Execute menu to build and run your programs. You can press Ctrl+F9 to compile a program. If you've made extensive changes to your header (.h) files and need to do a rebuild, that option is Ctrl+F11. Usually, the easiest option is F9, which performs a Compile & Run. The program output is shown in Figure 2.26.

Figure 2.26. The Hello World program is running!

Now I want to explain how to set up Dev-C++ for the static library version of Allegro. This version will let you build a program that has no dependency on the Allegro DLL. Let's just assume we're working with the Test_DevCpp program that you just created. I'll show you how to convert that project so that it compiles with the static Allegro library.

First, you have to install the MinGW version of DirectX inside the Dev-C++ folder. On the CD-ROM, look in the softwareDev-C++ 5.0DirectX Files folder. In this folder you will find lib and include. Copy both of these folders into C:Dev-C++. That will give you the library files needed to build the statically linked version of Allegro (which calls on DirectX to “do its stuff”).

Next, we can configure the project for the static library. Open the Project Options dialog box and click on the Parameters tab. As you'll recall, all you have to do to create a dynamically linked Allegro program is add—lalleg to the Linker box. To configure the project to use the static library, you have to insert quite a few more files to the Linker Options box and another option in the Compiler Options box.

In the first box, labeled Compiler, type in the static library option –ALLEGRO_ STATICLINK. Be sure to include the minus sign at the beginning, because this is a compiler option that is literally passed to GCC at the command line.

Next, in the Linker box, remove “–lalleg” and enter the following files instead:

-lalleg_s
-lgdi32
-lwinmm
-lole32
-ldxguid
-ldinput
-lddraw
-ldsound

Figure 2.27 shows the Project Options dialog box with the settings needed for a statically linked Allegro program.

Figure 2.27. Configuring Dev-C++ for a statically linked Allegro program.

That's all there is to configuring the static library. Since you just modified the previous project, you should still have the source code ready to compile. Go ahead and build the project by pressing F9, and the program should look just like it did before. The difference is, this new executable has no dependencies! That's right, you don't need the DLL file for this type of build.

If you have any problems compiling the program at this point, it is most likely due to missing DirectX files, missing Allegro include files, or missing Allegro library files. You do not need alleg42.dll to run the static version.