Monday, September 23, 2013

Box2D Build - MinGW for Code::Blocks (Windows, or not)

Our first step on to creating anything on game development is to make sure everything we need is ready for us to start mashing our keyboards. This means we need our IDEs and compilers working fine and our libraries are all just waiting for us to use them.

For this to happen, we need to:
  • Download the Source Code;
  • Get the binaries for our library; two ways:
    • Download Binaries for our compiler; or
    • Build it ourselves.
  • Include it on our project:
    • Set search directories and link it properly.
So, today, I'm going to give you a basic step-by-step guide on how to build Box2D, a C++ engine for simulating 2D rigid bodies physics.

"Why Box2D?",

you ask me.

Well, Box2D has been around for longer than I study game development (Sep, 07); it is stable, reliable, platform independent... I really see no reason to use any of the other engines in the market. Specially considering most of these engines were built over Erin Catto's algorithms. Some will even require you pay hundreds (even thousands) for a license, nonsense. Box2D is open source and released under the zlib license, that is a really permissive license allowing anyone to use, even for commercial projects, free of charge, with no additional requirements. More info on the license can be found here. As a note, Box2D does not require attribution (such on it MIT license!), so, if you actually do it, you're basically stating that you are awesome.

Examples of games built with Box2D are Crayon Physics Deluxe, Wold of Goo iirc; and Angry Birds (give it the credit already!).

On top of that, Box2D has the largest number of examples one can find. There use guides all over the internet, some are even in video (I don't really like video guides for programming). This way, even if you are one of the unfortunates following this blog ( Hi Bxn ^^, Hi Mom !! ) you'll not be stuck with my future horribly terrible guides on using it!

The problem with Box2D is that they, for some reason, do not consider MinGW and Code::Blocks professional enough. So, if you are not using the industry standard MS Visual Studio or XCode there'll be no IDE/Compiler project ready for you to use. That's why we need to do this the "hard" way; which is not that hard. There are some community created projects for it, but they are unofficial, not being included with the source nor kept up-to-date. Still, it is good for us beginners to really understand how compiling and linking works and how to build something outside of our lovely IDEs. This is just the perfect opportunity for an introductory challenge!

What Exactly are we doing?

First things first, let me just briefly (and probably wrongly) explain what we are doing here. Building a C++ library, such as Box2D, Allegro or any other, means we transforming the source code into a linkable file, that we can then use in our own projects, after we compile them. "Wait, What?"

Basically, we are compiling and linking the library, so it is ready to use. If we "copied and pasted" the library's functions to our project, made the necessary changes to the #includes and etc, we would be using it without previously building it. It would probably work, the library would compile along with your game after every "Clean" order. The problem with integrating the library with code editing is that it would be a tedious task that would take a really long time, and in the end deliver the same results; not worth it. We could also configure our projects to build our libraries along with our own code, but, given you are not modifying the library, it is just a waste of time, since it would need to be rebuilt with after every Clean order.

Building Box2D for MinGW and Code::Blocks

From this point forward, I am assuming you have already installed and configured MinGW and Code::Blocks properly, and does not have two MinGW conflicting folders. If you need, check this other post on how to install them.

As of today (Sep 2013) Box2D latest release is version 2.2.1, available at or google code.

Step 1 - Download the source code. or
Step 2 - Download and install CMake.
"Why use CMake if Box2D has prebuild4?", you're asking me. I don't know how to do it with prebuild4, simple as that. Tried it threee times, and hit threee different problems. So I just decided that there was no advantage over building with CMake, that I rarely hit any errors. If Box2D drop CMake support anytime soon (what I doubt, btw), I'll make a separate guide for premake; if I can figure it out.

To start the building process, it is wise to save your source code on a convenient place. Your directory structure doesn't have to be complex, but it should be convenient. In a following post, I'll talk a little about the directory structure for development. For now, I'll be using X:\GameDev\Libraries directory. Decompress Box2D there and you'll have the X:\GameDev\Libraries\Box2D_v2.2.1, and all of its subfolders.

Step 3 - Generate the MinGW Makefiles using CMake.
But how exactly?

  • Open CMake;
  • Define the folders;
  • Hit Configure;
    • The log should show "Configuring done" and Options in red;
    • Check the boxes that start with BOX2D;
  • Hit Configure (2nd time);
  • Hit Generate.

Go ahead and open CMake-gui. You'll see this window right here:

CMake Folders, Source and Build.

Note that I inserted two folders on the text boxes on the top of the window. The first box must be the base directory of Box2D and the second should be the Build folder.

Important Observation:
Inside of this folder X:\GameDev\Libraries\Box2D_v2.2.1 there must be a folder called Build. If you find another folder named Box2D_v2.2.1 instead, see if you can find the Build folder in it; if you do, choose this one for the first text area, and its Build folder for the second.
After setting up your source and build paths, hit Configure for the first time. If you haven't set your compiler, you'll see a dialog where you can select which one you wish to use (image); MinGW for this tutorial.

CMake Compiler Selection.

Choose your MinGW and press Finish. This is what you should see:

Configure should generate this output. The red stuff is not an error list, it's our build options.

Notice that CMake makes a test for a working compiler. If you fail this test, your compiler is not set up properly, check the bottom of the post.

Moving on, every one of these lines with a checkbox/text area is a build option. If yours are not red, but white, it just means that they have been loaded from a cached configuration, but it's fine; if that's case, it is a good idea to clear the cache, just click File -> Delete Cache on CMake; click Configure again.

I'm going to check all the boxes that starts with BOX2D and hit configure a second time.
Now hit Generate.

What we did was setting everything up for us to finish the building process with MinGW. In the end, your CMake should look just like this:

No error messages.

If you had any errors, try deleting the cache and repeating the process. Make sure the test CMake does with your compiler return a "-- works" result on both, gcc.exe and g++.exe.

Step 4 - Make.
Using the console.

Open your console and travel to the Box2D Build folder. In our example, the command would be:

C:\> X:
X:\> cd GameDev\Libraries\Box2D_v2.2.1\Build

If you don't know how to open the console, hit Super (aka Windows key) + R and type cmd, hit Enter.

On the console, once you found Box2D build folder, where we just set everything up using CMake, issue the following command:


If we did it all right, this is what you should see:

If it worked, under your Box2D_v2.2.1\Build\Box2D you'll find a file called libBox2D.a .
These .a files are exactly what we were trying to achieve!

Want to have some fun? Now that we did all of this, under Box2D_v2.2.1\Build\Testebed you'll find the Testbed.exe. Take a look on how Box2D is awesome!

This library is now ready to be used on Code::Blocks and MinGW. Actually, it is ready for use with any IDE that uses your installed MinGW, not necessarily C::B.

Downloading libBox2D.a and other .a files

For all of you who can't build it or are just too lazy to do it, I'll upload the .a files. But just try to build them yourselves, Ok? Knowing how to build libraries is really a necessary step on Game Development with C++.

I do not recommend this download to anyone, under any situation.

And that's it for today; over and out.

Troubleshooting CMake compiler test

May be this message exactly or something similar.

If this happens, you can try these steps:
  1. Add an environment variable called MINGWDIR with value C:/MinGW
  2. Add the cmake install folder to the windows Path environment variable.
There are lot's of guides on how to do this, but the basic procedure is
  • right clicking  on My Computer (or equivalent)
  • click Properties
  • Advanced Tab -> Environment Variables
There are going to be two lists, you should add the MINGWDIR on the bottom list. Edit the Path also on the bottom list. Restart your machine and try again.

Always remember to click Delete Cache under the File menu between tests.

If all of this does not work, try reinstalling MinGW and CMake and restarting the machine. If you still have any problems to make this work, I advise you to search possible solutions on the web and post on dev forums.