Building with Windows

German Version here

Get the sources

The source of OpenClonk is hold in a so-called version control system. Put simply, this is something that allows programmers to coordinate their work (see the Git article for how that works). For the moment, it's just a couple of files you want to download.

Install TortoiseGit

The notable difference to a simple download is that you need a special program to do it. Our version control system is Git, and we will use the TortoiseGit client. Follow that link and click "Download".

As the website tells you, the installation of TortoiseGit has two parts: TortoiseGit and msysGit. It also says that you should start with TortoiseGit, so let us get that installer first. Make sure to choose the right architecture for your version of Windows:

And walk through the installation. Just selecting the default options should get you through alright.

OpenClonk team members: If you want to use PuTTY to push commits, make sure to select the appropriate option along the way. Do it again for the msysGit installation below.

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the "Full installer for official Git" link will get you to another download page:

This installation will ask even more confusing questions. But again default options won't cause anything to break, I would just recommend deactivating some GUI options, as TortoiseGit already offers them:

After a bit of waiting and (if you're lucky) not a single request to restart your computer, this should have given you a working TortoiseGit installation.

Clone

Okay, now we are going to download the sources. Git calls this "cloning" because it's actually a lot more than just the sources you get. After you're done, you can check the Git Workflow page for how to work with your clone.

For now, just find a place where you want the source to be, open the context menu by right-click and select "Git Clone..." from the TortoiseGit menu:

A dialog will appear asking for the repository URL and the destination path. In our case, we want the source to be the OpenClonk repository. The URL you need is normally "git://git.openclonk.org/openclonk.git". Here's how it should look like:

OpenClonk team members: Use "ssh://git@git.openclonk.org/openclonk.git" instead and activate the option to auto-load the PuTTY key for maximum convenience.

After pressing "OK", TortoiseGit will work for a while. After watching a tortoise somersaulting for a while, it should finish. Congratulations, you now have the bleeding edge of OpenClonk development on your hard drive!

This a lot of stuff and most likely you won't understand much of it. Here's a quick orientation guide of the actually important bits:

• "docs" - the sources of our documentation
• "planet" - these are the game resources - scripts, graphics and everything to explain how to make a game out of them
• "src" - all the source code of the game engine. Lots of C++ ahead.

Get it to Compile

This is nice, but we are interested in seeing the game run, aren't we? For this, we need a program that will take all those C++ files and make an executable file out of it. Unfortunately, programming is complicated stuff so even setting up the tools and the environment has become a bit of science. But this won't stop us.

Get Microsoft Visual Studio

You can say what you want about Microsoft, but they sure make nice development environments. And they are even giving a lot of it away for free. We will use Visual Studio C++ 2012. Follow that link, find the 2012 Express Edition for Windows Desktop, then download the web installer:

Run it, accept the licensing terms, click the big "Install" link and accept the UAC prompt.

Then go make a coffee because the install will probably take a while. If the setup asks you to restart your computer, do so; it will continue when you log back in.

Get Dependencies

Like most big programs, OpenClonk doesn't stand on its own. Some things (like opening PNG images) were already programmed by other programers far better than we could ever do. This is why we have to get a few so-called "libraries" before Clonk can be built.

You could expend some effort try to find, download, and compile all those libraries by yourself, but that would take quite some time. Instead, just download one of the packages we've provided for your convenience. If you're trying to build a 32-bit binary of OpenClonk or you don't really know what this is all about, use the x86 package; for a 64-bit binary, use the amd64 package. Then unpack the .zip archive and put the "deps" folder into the directory where you also want your build files.

Get CMake

Before all this becomes useful, we still need something that tells the compiler how all those sources and libraries should be compiled together.

For this, Visual C++ needs a project file. But there is none - we have to consult another program to generate it for us. This might seem confusing - but the point is that there are a lot of build environments besides Visual Studio, and having all those project files next to each other would become a problem in the long run.

What we need is CMake. Follow that link and download the installer:

You know what to do.

After the installation, start the CMake GUI from the start menu. Put the path you cloned the repository into the source code path field. You can set the build path to any directory you want, but it is important that the "deps" folder from the last step is also in that directory.

Now click the "Configure" button in the lower left. It will ask what compiler we want to use. Select the compiler you want to use; either "Visual Studio 11" if you downloaded the 32-bit library package above, or "Visual Studio 11 Win64" if you got the 64-bit package.

If you get some error messages (in red), you're probably missing some dependencies. Don't worry if cmake complains about some missing paths, it shouldn't affect you.

The last step is to click the "Generate" button.

Your First Build

Okay, now we have everything needed to make OpenClonk run for the first time. Go into the source directory and double-click on the "openclonk.sln" file that should now have appeared:

Visual C++ should open and look similar to this:

We only want to build the engine, so select "openclonk" from the list, right-click and select "Set as Start-Up project"

Now press F5 (or, if you prefer, click the "Local Windows Debugger" button in the tool bar). Visual Studio will notice that you don't actually have a current compiled version of OpenClonk yet. Tell it to build one, and if you like also tell it to always just automatically build a new version using the check box.

If all goes well, after a couple of minutes you'll be looking at the OpenClonk main menu.

In case you are wondering why OpenClonk suddenly starts in some kind of pseudo windowed mode: This is because we just built a debug build (note the "dbg" after the version?). This build is a bit slower but allows you to get a better look at the internals of the engine while it's running. Maybe we'll have another article about that soon.