Building with Windows
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. 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. We will later see what we can do with this.
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". If you're a developer, use "ssh://git@git.openclonk.org/openclonk.git" and set it to auto-load the PuTTY key. Here's how it should look like in both cases:
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++ 2010. Follow that link, click yourself through the ever-shifting Microsoft website to the 2010 Express Edition, until you arrive at something that ideally looks like follows:
The installer will offer us a lot of stuff we don't really need for OpenClonk. You should uncheck it to make the installation faster.
You will most likely stare at the following screen for a bit. It won't take that long, and for me didn't even restart the computer like it suggested it would.
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 try to search and download all those libraries by hand, but that would be pretty boring. Instead, just download this package that contains everything you need to build Clonk.
Unpack both directories into the same path you put all the other files. Don't worry, nothing will get overwritten in "planet".
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.
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, for example "Visual Studio 10". Do not pick the Win64 option, as the precompiled libraries are 32 bit.
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 "clonk" from the list, right-click and select "Set as Start-Up project"
Now select "Build Solution" from the "Build" menu (or just press F7). No, I don't know what "solution" means. Drink a cup of coffee or two while you wait for the compiler to do its job.
Eventually, you will arrive at this screen.
Nevertheless, you can now select "Start Debugging" from the "Debug" menu (or just press F5) and should be greeted by the startup screen of a fresh OpenClonk build!
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.
Enabling sound and DirectX
So far, the version of OpenClonk you can compile runs with OpenGL only and without sound. Here is how to enable both DirectX and sound:
Download the latest DirectX SDK from the Microsoft website and install it. For sound, download the FMOD 3 Programmers API and unpack it somewhere. Now, you need to copy api/fmod.dll into your planet/ directory, all the files that are in api/inc to planet/deps/include and api/lib/fmodvc.lib to planet/deps/lib.
Thats it. Now, you need to re-run CMake and check both USE_DIRECTX and USE_FMOD. Compiling the game with VC++ will now produce a build where you can hear the sound and use direct x.