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.

A. Configuring a Win32 Application

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

1. Open Microsoft Visual Studio
2. Click on File / New
3. Choose Win32 Application
4. Enter your Project Name and hit "OK"
5. Select "An Empty Project" and press "Finish"
6. Hit "OK" on the status window that pops up

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!

1. Click on "Build" / "Configurations"
2. Click the "Add..." button
3. In the "Configuration" textbox, enter "Profile" and Click "OK"
4. Click "Close"

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 do either, 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

1. Click on "Projects / Settings"
2. Make sure that the project name (the first item) is selected on the ListView on the left hand side



3. Select "Win32 Release" in the "Settings For" drop down
4. Under the "Code Generation" in the "C/C++" tab, choose "Multithreaded DLL"
5. Under the "Object/library modules" in the "Link" tab, replace everything with "alleg.lib"



6. Select "Win32 Debug" in the "Settings For" drop down
7. Under the "Code Generation" in the "C/C++" tab, choose "Debug Multithreaded DLL"
8. Under the "Object/library modules" in the "Link" tab, replace everything with "alld.lib"



9. Select "Win32 Profile" in the "Settings For" drop down
10. Under the "Code Generation" in the "C/C++" tab, choose "Multithreaded DLL"
11. Under the "Object/library modules" in the "Link" tab, replace everything with "allp.lib"
12. Checkmark the "Enable Profiling" in the "Link" tab

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.)

1. Click on "Projects / Settings"
2. Make sure that the project name (the first item) is selected on the ListView on the left hand side



3. Select "Win32 Release" in the "Settings For" drop down
4. Under the "Code Generation" in the "C/C++" tab, choose "Multithreaded DLL"
5. Under the "Object/library modules" in the "Link" tab, replace everything with "alleg_s.lib kernel32.lib user32.lib gdi32.lib comdlg32.lib ole32.lib dinput.lib ddraw.lib dxguid.lib winmm.lib dsound.lib"



6. Select "Win32 Debug" in the "Settings For" drop down
7. Under the "Code Generation" in the "C/C++" tab, choose "Debug Multithreaded DLL"
8. Under the "Object/library modules" in the "Link" tab, replace everything with "alld_s.lib kernel32.lib user32.lib gdi32.lib comdlg32.lib ole32.lib dinput.lib ddraw.lib dxguid.lib winmm.lib dsound.lib"



9. Select "Win32 Profile" in the "Settings For" drop down
10. Under the "Code Generation" in the "C/C++" tab, choose "Multithreaded DLL"
11. Under the "Object/library modules" in the "Link" tab, replace everything with "allp_s.lib kernel32.lib user32.lib gdi32.lib comdlg32.lib ole32.lib dinput.lib ddraw.lib dxguid.lib winmm.lib dsound.lib"
12. Checkmark the "Enable Profiling" in the "Link" tab

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" / "New"
2. Choose "C / C++ Source File", enter the filename, and press "OK"
   
   
3. Enter the following code:

   /* #define ALLEGRO_STATICLINK  */
   /* #define USE_CONSOLE */
   #include "allegro.h"
   
   int main(void)
   {
     allegro_init();
     allegro_message("Hello World");
     return 0;
   }
   END_OF_MAIN();
   

   (Note: If you are statically linking or using a Win32 Console Application, then uncomment the associated lines.)
   
   
4. Compile and Run the program. (CTRL-F5)