Building with Windows

Revision as of 17:01, 13 May 2018 by Luchs (talk | contribs) (Update links, replacing with github)

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 - if you want, you can afterwards read the Git article to see 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".

Build windows tgit.png

Proceed to the "Download" page and select the appropriate installer. If unsure, you probably want the 64-bit version:

Build windows tgit2.png

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

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.

Build windows tgit4.png

You also need to install Git for Windows, which is what actually does all the work behind the scenes. Following this link will get you to another download page:

Build windows tgit3.png

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:

Build windows tgit5.png

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.


Okay, now we are going to download the sources. Git calls this "cloning" because it's actually a lot more than just the sources. 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:

Build windows tgit6.png

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 "". Here's how it should look like (note that the screenshot is showing an outdated URL):

OpenClonk team members: Use "" instead and activate the option to auto-load the PuTTY key for maximum convenience.

Build windows tgit pub.png

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

Build windows tgit finish.png

There is 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 2015 Express for Desktop. Follow that link, then click on "Visual Studio 2015" and "Express 2015 for Desktop":

Make extra sure you got the "Express 2015 for Desktop.

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.

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:

These packages are made for unpacking directly into the "openclonk" folder you created above, which will put a couple of DLL files into the root and create a "deps" folder. If you would like to organise the dependencies yourself, use the original dependency files provided by Isilkor (x86 and amd64).

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:

Build windows cmake1.png

You know what to do.

Build windows cmake2.png

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.

Build windows cmake3.png

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 14 2015" if you downloaded the x86-bit library package above, or "Visual Studio 14 2015 Win64" if you got the amd64-bit package.

Build windows cmake4.png

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:

Build windows build1.png

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

Build windows build2.png

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

Build windows build3.png

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.

Build windows outofdate.png

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

Openclonk first start.jpg

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.