Thursday, September 26, 2013

Creating the Code::Blocks Project and Linking Allegro 5 (MinGW)

 Hello again,

This is the first post where we'll talk about a real IDE project, adding a library and linking it. Following, we'll write a code snippet to try and compile the project and see if it compiles well (0 warnings) and works as intended.

From this point, I'm assuming you've properly installed Code::Blocks and MinGW (with MSYS)  as well as downloaded the Allegro 5.0.10 binaries for our MinGW.

Creating the Workspace


Before everything, we should create our workspace. It is up to you how you handle your directories, but a good directory configuration can save you time.
I've been using this configuration for quite some time now and I feel really comfortable with it. I have no problems when formatting my machine or synching it with my second one. It has some more directories than those I'll be listing here, but they'd be useless for us, so I'll simply omit them for now, for simplicity's sake.

  • C:
    • GameDev
      • Projects
        • Game1
        • Game2
      • Libraries
      • Resources
Note that no folder should have spaces or special characters, since this leads to problems over the entire process of developing the software. One other point is that the folder GameDev can be copied and pasted on any machine and the relative paths of our project files will still be intact. If you wish, you can add sub-folders inside Libraries to hold different platform builds (Win32, Linux, OUYA [...]). The Resources folder is where I put everything related to documentation: game design documents, technical design documents, libraries manuals [...].

Code::Blocks will save everything a project needs inside its own folder. It may not always be the best solution, but it works; Microsoft VS does it and no one complains, so I guess we'll be fine.

Creating the Project

Now open up Code::Blocks click create a new project on the welcome page. You'll see a list of project templates, some functional, some not; since we are using Allegro (and there's no template) go for an Empty Project. I'll be calling our prototype Spacerock Miners, as a reference to asteroid mining. Since we should not have spaces on our project path, let's call the project SpacerockMiners without the space.

When you're finished with the wizard (nothing really complex about it) you'll be left with a blank project without any files. Go to New -> File... -> C/C++ Source and create a main.cpp for us to test our compiler.

Add a hello world code to test the IDE, the project and the compiler.

Build and Run it. You'll see that Code::Blocks opens the console and prompts the message. If your build did not work, you'll probably have to troubleshoot your compiler/IDE interaction.

Linking Allegro


Now that our project is up and the compiler is tested and working we will test our library. To do so, we need to link it to the project, include its headers and run a simple test code to see whether is working or not.

If you are following this guide, you should decompress allegro 5 in our Libraries folder. This means that the Libraries should have a folder called allegro-5.0.10-mingw-4.7.0 (or simply allegro5 if you want to rename it) with a bin, a lib and an include folder in it.

Note - MinGW installation under Windows.
It is possible to install Allegro on your MinGW if you build it yourself. It does take longer than downloading the binaries, but saves time when creating projects and build configurations. You would not need to add any .a files under linker options, for example. After you successfully configure your Allegro build with CMake, run mingw32-make to see that allegro is built. Right after your make command finishes, issue a mingw32-make install command, and it will install Allegro making our linking easier. Still, this guide will assume you downloaded the binaries.

You can however install the library manually, by copying your .a files to your MinGW folder.

Let's go back to our main.cpp and include an Allegro header, as well as some test code. As of here, I must warn you guys that we may need some .dll files. If you are on an Ubuntu computer, you'll probably have no problems linking, compiling nor running; If on a Mac, I have no idea whatsoever (sorry). Moving on, we have to add our Allegro files to our project linker options.

For this guide, we'll use something called Static Linking for Allegro. This will save us from having to copy the dlls to every project folder we create (release and debug) or to our main system dll folder. More information on this here: Allegro - Static and Dynamic link.

One annoying thing about complex libraries is that the order with which you add the files matters. Also important is that we'll use the -static-mt-debug.a files, they are the ones that carries both Allegro and standard C statically, so we clean all needs for dll files; needless to say they are for the debug build, if we ever need a release build we'll link it properly.

As the Allegro Library is modular, we don't need to always add all of these; linking acodec is only necessary if we are going to use sounds. The order of the files and the brief description are available here: Allegro manual. As we are making a simple Hello World program we'll only be adding two files: the core and the primitives library.

liballegro-5.0.10-static-mt-debug.a
liballegro_primitives-5.0.10-static-mt-debug.a

These are the only files we need to link now.

First things first, open C::B and open our Spacerock Miners project. On the top menu, click Project -> Build Options... You'll see that this window has six tabs, specially: Compiler Settings, Linker Settings and Search Directories. The other three are not important for us now.



Select the DEBUG build on the list on the left (should have only SpacerockMiners, Debug and Release).

On Compiler Settings,
Go to Other Options and add this:
`pkg-config --cflags --libs allegro-5.0 allegro_primitives-5.0`
Go to #defines and write this on the text area:
ALLEGRO_STATICLINK
Notice that, on the option `pkg-config, that's not an apostrophe, but a backtick; as in `, not '.

 On the Search directories,
  • Add Allegro's include folder under the compiler tab;
  • Add Allegro's lib folder under the linker tab.


On the Linker Settings,
Add the two allegro modules we need:

additionally, as we are going to generate a self-sufficient application, we'll need to add other .a files from MinGW directory. So click Add and go to your MinGW/lib folder (probably C:/MinGW/lib). Now copy and paste the white text below on the filename and hit ok.
libgdiplus.a; libuuid.a; libkernel32.a; libwinmm.a; libpsapi.a; libopengl32.a; libglu32.a; libuser32.a; libcomdlg32.a; libgdi32.a; libshell32.a; libole32.a; libadvapi32.a; libws2_32.a; libshlwapi.a
You can also add file by file. More information here.
Now we have configured our compiler and linker options, we should be able to compile Allegro5 code. I'll add a sample code here for you guys to test and get started.

This is a simple code that creates a window and draws an ugly red triangle. It closes 3 seconds after it opens.



If you can compile this, you've done it!

In case you encounter errors, try repeating the steps for a new project. You can find other guides on this on the allegro wiki, such as this one here. If you can't find the .a files, you have not built the library. In this case, download the binaries from allegro.cc and decompress them inside our Libraries folder.

That's all for today, I'll probably update this guide once or twice.
Over and Out.