Latest revision as of 17:13, 13 May 2018

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".

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

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.

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:

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. 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 "https://github.com/openclonk/openclonk". Here's how it should look like:

OpenClonk team members: Use "git@github.com:openclonk/openclonk" 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 progress bar for a while, it should finish. Congratulations, you now have the bleeding edge of OpenClonk development on your hard drive!

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":

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:

the x86 package (we'll assume this one)
the amd64 package

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:

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

@@ Line 1: / Line 1: @@
+[[DE:Kompilieren unter 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. For the moment, it's just a couple of files you want to download.
+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 [[Git Workflow|the Git article]] to see how that works. For the moment, it's just a couple of files you want to download.
-== Install TortoiseHg ==
+== Install TortoiseGit ==
-The notable difference to a simple download is that you need a special program to do it. Our version control system is Mercurial, and we will use the [http://bitbucket.org/tortoisehg/stable/wiki/Home TortoiseHg] client. Follow that link and click "Download".
+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 [https://tortoisegit.org/ TortoiseGit] client. Follow that link and click "Download".
+[[File:build_windows_tgit.png|860px]]
-[[File:build_windows_thg2.png]]
+Proceed to the "Download" page and select the appropriate installer. If unsure, you probably want the 64-bit version:
-We pick the most current version for Windows available, in this case version 0.8. Note there might be a newer version available when you visit the page.
+[[File:build_windows_tgit2.png|860px]]
+And walk through the installation. Just selecting the default options should get you through.
-[[File:build_windows_thg3.png]]
+''OpenClonk team members:'' If you want to use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY] to push commits, make sure to select the appropriate option along the way. Do it again for the msysGit installation below.
-After the file has finished downloading and we have managed to get through all the warning boxes, we finally arrive in the installer. Nothing interesting to see here, just install it somewhere.
+[[File:build_windows_tgit4.png]]
+You also need to install [https://git-for-windows.github.io/ Git for Windows], which is what actually does all the work behind the scenes. Following this link will get you to another download page:
-[[File:build_windows_thg4.png]]
+[[File:build_windows_tgit3.png|860px]]
-I won't lie, I never restart my computer when I'm asked to. You might do so, but from what I know you only get a few colorful icons as a reward.
+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:
-== Clone ==
+[[File:build_windows_tgit5.png]]
-Okay, now we are going to download the sources. Mercurial 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 extra stuff.
+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.
-For now, just find a place where you want the source to be, open the context menu by right-click and select "Clone a repository" from the "TortoiseHg" menu:
-[[File:build_windows_thg5.png]]
+== Clone ==
-A dialog will appear asking for the source and destination paths. In our case, we want the source to be the OpenClonk repository.  The URL you need is [http://hg.openclonk.org/ http://hg.openclonk.org/]". Put it into the "Source Path" field and click the "Clone" button:
+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.
-[[File:build_windows_thg6.png]]
+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:
+[[File:build_windows_tgit6.png]]
-A log window will open and TortoiseHg will work for a while. Eventually, it should look like this:
+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 "https://github.com/openclonk/openclonk".  Here's how it should look like:
-[[File:build_windows_thg7.png]]
+''OpenClonk team members:'' Use "git@github.com:openclonk/openclonk" instead and activate the option to auto-load the PuTTY key for maximum convenience.
+[[File:build_windows_tgit_pub.png]]
-Congratulations, you now have the bleeding edge of OpenClonk development on your hard drive!
-[[File:build_windows_thg8.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!
+[[File:build_windows_tgit_finish.png|860px]]
-At first glance, this a lot of stuff and most likely you won't understand much of it. The good news is that you don't need to pay attention to most of it. The interesting parts are:
+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 the documentation you might know from the Clonk Homepage
+* "docs" - the sources of our [http://docs.openclonk.org/en/sdk/ documentation]
-* "planet" - game resources. If you have used Clonk's development mode, the contents will probably look familiar.
+* "planet" - these are the game resources - scripts, graphics and everything to explain how to make a game out of them
-* "src" - the source code of the engine
+* "src" - all the source code of the game engine. Lots of C++ ahead.
 = Get it to Compile =
@@ Line 57: / Line 61: @@
 == 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 [http://www.microsoft.com/express/vc/#webInstall Visual Studio C++ 2008], but MSVC 2010 also works. Follow that link, select your language and select "Download".
+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 [https://www.visualstudio.com/downloads/download-visual-studio-vs# Visual Studio 2015 Express for Desktop]. Follow that link, then click on "Visual Studio 2015" and "Express 2015 for Desktop":
-[[File:build_windows_msvc1.png]]
-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.
+[[File:Build_windows_msvc2015.png|860px|Make extra sure you got the "Express 2015 for Desktop.]]
-[[File:build_windows_msvc2.png]]
-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.
-[[File:build_windows_msvc3.png]]
+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 ==
@@ Line 76: / Line 72: @@
 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 [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.
+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:
-[[File:build_windows_deps.png]]
+* [http://people.ds.cam.ac.uk/pw410/out/openclonk-deps-vs140-i386-easy.7z the x86 package] (we'll assume this one)
+* [http://people.ds.cam.ac.uk/pw410/out/openclonk-deps-vs140-amd64-easy2.7z the amd64 package]
+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 ([https://www.nosebud.de/~nh/openclonk/openclonk-deps-vs140-i386.7z x86] and [https://www.nosebud.de/~nh/openclonk/openclonk-deps-vs140-amd64.7z amd64]).
-Unpack both directories into the same path you put all the other files. Don't worry, nothing will get overwritten in "planet".
 == Get CMake ==
@@ Line 91: / Line 87: @@
 What we need is [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:
-[[File:build_windows_cmake1.png]]
+[[File:build_windows_cmake1.png|860px]]
@@ Line 100: / Line 96: @@
 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.
 [[File: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, for example "Visual Studio 9 2008". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.
+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.
 [[File:build_windows_cmake4.png]]
@@ Line 116: / Line 113: @@
 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:
-[[File:build_windows_build1.png]]
+[[File:build_windows_build1.png|860px]]
 Visual C++ should open and look similar to this:
-[[File:build_windows_build2.png]]
+[[File:build_windows_build2.png|860px]]
-We only want to build the engine, so select "clonk" from the list, right-click and select "Set as Start-Up project"
+We only want to build the engine, so select "openclonk" from the list, right-click and select "Set as Start-Up project".
 [[File: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.
-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.
+[[File:build_windows_outofdate.png]]
-Eventually, you will arrive at this screen and probably wonder who taught those coders the kind of shoddy practices that result in more then 600 warnings.
+If all goes well, after a couple of minutes you'll be looking at the OpenClonk main menu.
-[[File:build_windows_build4.png]]
-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!
 [[File: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.
-= 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 [http://msdn.microsoft.com/en-us/directx/default.aspx DirectX SDK] from the Microsoft website and install it. For sound, download the [http://www.fmod.org/index.php/download#FMOD3ProgrammersAPI 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.

Building with Windows: Difference between revisions