The Allegro Guide

I. Creating a Project

Using Allegro with Microsoft Visual Studio is simple once you get the workspace configured. For most applications, you will want to use a "Win32 Application" and link against the optimized library. While writing the code, however, you will probably want to use the debugging and profiling modes. We are assuming you already have Allegro already installed for MSVC 7.

A. Configuring a Win32 Application

If you want to create a game with graphics, then you need to create a 'Win32 Application' workspace. (figure 1)

1. Open Microsoft Visual Studio .NET
2. Click on File / New / Project
3. Choose "visual C++ Projects" / "Win32 Project"
4. Enter your project Name, choose a Location and hit "OK"
5. Select "Application Settings" and choose "Empty project"
6. Hit "Finish"

Your workspace has been set up, but now we need to link to the Allegro library. You technically only need to set up the optimized or debugging version, but it's recommended to set up all three versions of Allegro - including the profiling. Remember that you must have already built all these versions of Allegro before you can use them!

In order to get to the settings, you will need to Right-click on the Project Name in the "Solution Explorer" and choose "Properties". (figure 2)

1. Click "Configuration Manager..."
2. Select "<New...>" from the "Active Solution Configuration" drop down.
3. Enter "Profile" in the "Solution Configuration Name".
4. Hit "OK".

Now that we have all the configurations in place, we must set them up. We need to make the decision now if we want to statically link or dynamically link. Dymamically linking means that you must distribute the Allegro DLL along with your files. If you statically link, your executable will be much bigger (the size of the DLL), but you will not need to distribute the DLL. If you have more than one executable, you should probably link dynamically to save space. If you want to be able to use both methods, then you can repeat the steps 1-4 from above and add three more configurations entitled "Static Release, "Static Profile", and "Static Debug".

In short, you only need to do one or the other. If you are not sure, then linking dynamically is the safer option.

1. Dynamically Linking

Debug Build
1. Under the Configuration drop-down, choose "Debug"
2. In the folder tree, choose "Configuration Properties" / "C/C++" / "Code Generation"
3. Select "Multi-threaded Debug DLL" in "Runtime Library"
4. In the folder tree, choose "Configuration Properties" / "Linker" / "Input"
5. Enter "alld.lib" in "Additional Dependencies"
6. Click "Apply"

Optimized (Release) Build
1. Under the Configuration drop-down, choose "Release"
2. In the folder tree, choose "Configuration Properties" / "C/C++" / "Code Generation"
3. Select "Multi-threaded DLL" in "Runtime Library"
4. In the folder tree, choose "Configuration Properties" / "Linker" / "Input"
5. Enter "alleg.lib" in "Additional Dependencies"
6. Click "Apply"

Profile Build
1. Under the Configuration drop-down, choose "Profile"
2. In the folder tree, choose "Configuration Properties" / "C/C++" / "Code Generation"
3. Select "Multi-threaded DLL" in "Runtime Library"
4. In the folder tree, choose "Configuration Properties" / "Linker" / "Input"
5. Enter "allp.lib" in "Additional Dependencies"
6. Click "Apply"

2. Statically Linking

(Note: If you have chosen to configure both dynamic and static links, make sure to select the Static configurations in the steps below.)

Static Debug Build
1. Under the Configuration drop-down, choose "Debug"
2. In the folder tree, choose "Configuration Properties" / "C/C++" / "Code Generation"
3. Select "Multi-threaded Debug DLL" in "Runtime Library"
4. In the folder tree, choose "Configuration Properties" / "C/C++" / "Preprocessor"
5. Enter "ALLEGRO_STATICLINK" in "Preprocessor Definitions"
6. In the folder tree, choose "Configuration Properties" / "Linker" / "Input"
7. Enter "alld_s.lib kernel32.lib user32.lib gdi32.lib comdlg32.lib ole32.lib dinput.lib ddraw.lib dxguid.lib winmm.lib dsound.lib" in "Additional Dependencies"
8. Click "Apply"

Static Optimized (Release) Build
1. Under the Configuration drop-down, choose "Release"
2. In the folder tree, choose "Configuration Properties" / "C/C++" / "Code Generation"
3. Select "Multi-threaded DLL" in "Runtime Library"
4. In the folder tree, choose "Configuration Properties" / "C/C++" / "Preprocessor"
5. Enter "ALLEGRO_STATICLINK" in "Preprocessor Definitions"
6. In the folder tree, choose "Configuration Properties" / "Linker" / "Input"
7. Enter "alleg_s.lib kernel32.lib user32.lib gdi32.lib comdlg32.lib ole32.lib dinput.lib ddraw.lib dxguid.lib winmm.lib dsound.lib" in "Additional Dependencies"
8. Click "Apply"

Static Profile Build
1. Under the Configuration drop-down, choose "Profile"
2. In the folder tree, choose "Configuration Properties" / "C/C++" / "Code Generation"
3. Select "Multi-threaded DLL" in "Runtime Library"
4. In the folder tree, choose "Configuration Properties" / "C/C++" / "Preprocessor"
5. Enter "ALLEGRO_STATICLINK" in "Preprocessor Definitions"
6. In the folder tree, choose "Configuration Properties" / "Linker" / "Input"
7. Enter "allp_s.lib kernel32.lib user32.lib gdi32.lib comdlg32.lib ole32.lib dinput.lib ddraw.lib dxguid.lib winmm.lib dsound.lib" in "Additional Dependencies"
8. Click "Apply"

The workspace is entirely configured now! Skip down to the section entitled "Compiling Source Code" to get your first program compiled.

B. Configuring a Console Application

If you just want to use Allegro for a text console, then you can follow the above instructions, except you will need to choose "Win32 Console Application" when first creating the project. Also, you will need to define "USE_CONSOLE" before you include <allegro.h>, as illustrated below.

II. Compiling Source Code

For the sake of simplicity, we will set up a program from one source file that should display the words "Hello World" in a pop up dialog box.

1. Click on "File" / "Add New Item..."
2. Choose "C++ File", enter the Name, and press "Open"
   
   
3. Enter the following code:

   #include <allegro.h>
   
   int main(void)
   {
     allegro_init();
     allegro_message("Hello World");
     return 0;
   }
   END_OF_MAIN();
   

4. Compile and Run the program. (CTRL-F5)