OpenClonk Wiki - User contributions [en]

Building with Windows

2015-10-04T19:06:14Z

PeterW: Image sizes

[[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 - 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 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 [https://tortoisegit.org/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

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

[[File:build_windows_tgit2.png|860px]]

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

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

[[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_tgit3.png|860px]]

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:

[[File: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.

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

[[File: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 "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.

[[File: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!

[[File:build_windows_tgit_finish.png|860px]]

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 [http://docs.openclonk.org/en/sdk/ 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 [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_msvc2015.png|860px|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:

* [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]).

== 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 [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File: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.

[[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; 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]]

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:

[[File:build_windows_build1.png|860px]]

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

[[File:build_windows_build2.png|860px]]

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.

[[File:build_windows_outofdate.png]]

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

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

Building with Windows

2015-10-04T19:04:53Z

PeterW: Windows 10 / MSVC 2015 version

[[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 - 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 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 [https://tortoisegit.org/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

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

[[File:build_windows_tgit2.png|860px]]

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

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

[[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_tgit3.png|860px]]

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:

[[File: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.

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

[[File: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 "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.

[[File: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!

[[File: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 [http://docs.openclonk.org/en/sdk/ 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 [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_msvc2015.png|860px|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:

* [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]).

== 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 [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File: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.

[[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; 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]]

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:

[[File:build_windows_build1.png]]

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

[[File: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".

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

[[File:build_windows_outofdate.png]]

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

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

File:Openclonk first start.jpg

2015-10-04T18:37:30Z

PeterW: PeterW uploaded a new version of File:Openclonk first start.jpg

Screenshot of the first start of Openclonk.

File:Build windows build3.png

2015-10-04T18:32:38Z

PeterW: PeterW uploaded a new version of File:Build windows build3.png

File:Build windows build2.png

2015-10-04T18:32:25Z

PeterW: PeterW uploaded a new version of File:Build windows build2.png

File:Build windows build1.png

2015-10-04T18:32:14Z

PeterW: PeterW uploaded a new version of File:Build windows build1.png

File:Build windows cmake4.png

2015-10-04T18:31:52Z

PeterW: PeterW uploaded a new version of File:Build windows cmake4.png

File:Build windows cmake3.png

2015-10-04T18:31:40Z

PeterW: PeterW uploaded a new version of File:Build windows cmake3.png

File:Build windows cmake2.png

2015-10-04T18:31:31Z

PeterW: PeterW uploaded a new version of File:Build windows cmake2.png

File:Build windows cmake1.png

2015-10-04T18:31:22Z

PeterW: PeterW uploaded a new version of File:Build windows cmake1.png

File:Build windows msvc2015.png

2015-10-04T18:30:30Z

PeterW:

File:Build windows tgit finish.png

2015-10-04T18:29:39Z

PeterW: PeterW uploaded a new version of File:Build windows tgit finish.png

File:Build windows tgit pub.png

2015-10-04T18:29:28Z

PeterW: PeterW uploaded a new version of File:Build windows tgit pub.png

File:Build windows tgit6.png

2015-10-04T18:29:10Z

PeterW: PeterW uploaded a new version of File:Build windows tgit6.png

File:Build windows tgit5.png

2015-10-04T18:28:52Z

PeterW: PeterW uploaded a new version of File:Build windows tgit5.png

File:Build windows tgit3.png

2015-10-04T18:28:41Z

PeterW: PeterW uploaded a new version of File:Build windows tgit3.png

File:Build windows tgit4.png

2015-10-04T18:28:31Z

PeterW: PeterW uploaded a new version of File:Build windows tgit4.png

File:Build windows tgit4.png

2015-10-04T18:28:07Z

PeterW: PeterW uploaded a new version of File:Build windows tgit4.png

File:Build windows tgit2.png

2015-10-04T18:27:55Z

PeterW: PeterW uploaded a new version of File:Build windows tgit2.png

File:Build windows tgit.png

2015-10-04T18:26:53Z

PeterW: PeterW uploaded a new version of File:Build windows tgit.png

Development

2013-01-23T12:14:49Z

PeterW: /* Build OpenClonk Yourself */ Fixed Mercurial references

__NOTOC__

OpenClonk is an open project. That means it depends on people coming in and helping out. People just like you! This page should give you an idea what you could do in order to get involved.

=== Use Development Snapshots ===

OpenClonk is continously in development. The "current" version can change daily! If you want to follow the development, it is a good idea to make sure you are able to run development versions. You will not need to build them yourself - just use the development snapshots linked below and you should be ready to go.

* Development Snapshots - [http://www.openclonk.org/nightly-builds/ www.openclonk.org/nightly-builds/]
* Blog - [http://blog.openclonk.org blog.openclonk.org]
* Changelog - [http://git.openclonk.org/openclonk.git git.openclonk.org/openclonk.git]
* Browse source - [http://git.openclonk.org/openclonk.git/tree/refs/heads/master git.openclonk.org/openclonk.git/tree/refs/heads/master]

=== Report Bugs ===

We cannot possibly account for every possible configuration out there. If you see something that's wrong, we would really like to know about it. Especially if you are willing to actively work with us in finding a solution for the problem.

Here's how you can reach us:

* IRC - [irc://irc.euirc.net/openclonk-dev/ #openclonk-dev] on irc.euirc.net (Problems connecting? Use irc.ham.de.euirc.net)
* Bugtracker - [http://bugs.openclonk.org bugs.openclonk.org]
* Forum - [http://forum.openclonk.org forum.openclonk.org]

=== Contribute Scripts or Game Content ===

Just like Clonk Rage before, most things in OpenClonk can be changed without touching the engine. Instead, we rely on a script language and a flexible game content system to make up our game content. This means that you can get involved easily - without having to learn C++ first! Traditionally, developing own objects and scenarios and sharing them with others has been how pretty much all of today's developers started out.

* Developer Documentation [http://docs.openclonk.org/en/sdk/ docs.openclonk.org/en/sdk/]
* Forum - [http://forum.openclonk.org forum.openclonk.org]
* Style Guide - [http://wiki.openclonk.org/w/C4Script_Style_Guidelines wiki.openclonk.org/w/C4Script_Style_Guidelines]
* Contribute changes - [[Git Workflow]]

=== Build OpenClonk Yourself ===

When delving deeper into OpenClonk, you will often find yourself in the situation that you need a closer look at what makes OpenClonk tick internally. At that point, it is a good idea to assume the perspective of developers - get the source code and build it in your own development environment.

* Tutorial for Windows - [http://wiki.openclonk.org/w/Building_with_Windows wiki.openclonk.org/w/Building_with_Windows]
* General instructions - [http://wiki.openclonk.org/w/Build_OpenClonk wiki.openclonk.org/w/Build_OpenClonk]
* Git Workflow Guide - [http://wiki.openclonk.org/w/Git_Workflow wiki.openclonk.org/w/Git_Workflow]
* Git Repository - [http://git.openclonk.org/openclonk.git git.openclonk.org/openclonk.git]
* Source Code Structure - [http://wiki.openclonk.org/w/Source_code_structure wiki.openclonk.org/w/Source_code_structure]

=== Hack the OpenClonk Engine ===

Maybe you already are well-versed in C++ and want to help out actually diagnosing problems? Or - even better - have your own ideas on engine improvements? We are always glad to look at patches.

* Wondering where to start? - [[GSoC2011Ideas|Ideas page]]
* Debugging synchronization losses - [http://wiki.openclonk.org/w/Sync_losses wiki.openclonk.org/w/Sync_Losses]
* Style Guide - [http://wiki.openclonk.org/w/Style_Guidelines wiki.openclonk.org/w/Style_Guidelines]
* Forum, developers' corner - [http://forum.openclonk.org/board_show.pl?bid=5 forum.openclonk.org]
* Contribute changes - [[Git Workflow]]

=== Legal Stuff ===

OpenClonk uses the ISC license for code (engine and script) and CC-by for most other media. Read more about the [[License | license stuff]] here.

File:Build windows tgit pub.png

2012-12-03T20:16:35Z

PeterW: uploaded a new version of "File:Build windows tgit pub.png"

Git Workflow

2012-12-02T10:28:59Z

PeterW: /* Creating a Patch */

As an open source project, we want to make it easy for a lot of people to work on
our code - even people that aren't directly involved in the project!
That's why we use a distributed version control system called [http://git-scm.com/ Git],
which makes sure that all files stay consistent and it's not too easy to lose your data
when things get complicated. This article will walk you through how you can use this system
to organize and submit your changes to OpenClonk.

We will assume here that you have a clone of the OpenClonk repository like the one
you created if you followed the [[Building_with_Windows|Windows build tutorial]]. If you haven't, just follow the tutorial and return here after you have finished the "Clone" section.
The screenshots and explanations will also be somewhat specific to TortoiseGit.
On the other hand, the workflow is equally viable no matter what Git interface you use.

= Committing your Changes =

The first step is to actually make some meaningful changes to OpenClonk.
TortoiseGit will detect your work and automatically mark files or directories that have changed:

[[File:git_work_commit1.png]]

To register your changes with Git, you need to "commit" them using the "Git Commit" entry from the right-click menu.
Here you can select what files you want to include in the commit, and give a message
describing what you have done. Try to give a short summary of the change in the first
line, followed by more details and explanations after one empty line.

[[File:git_work_commit2.png]]

It is generally a good idea to commit early, as registering changes with Git means they will be a lot harder to lose.
It's a good idea to do this even if you know that you will want to do additional changes to the commit later:
The commit window allows you to "amend" the last commit so you
can keep working on it.

For even more flexibility, simply create another
commit for additional changes and [[#Reorganizing Changes|"squash" them later]]. This is also a good idea because it allows
you to go back and forth between revisions until you are convinced that your change works. It might even be
a good idea to mark commits that you want to be merged with a marker like "[squash!]" so
you don't forget to merge the changes later on.

= Synchronizing your Repository =

OpenClonk is under constant development, and it's generally a good idea to stay up-to-date.
Maybe uninuitively, this is especially vital if you are thinking of submitting a change:
You need to make sure that your changes work with where development is currently at.

Use the "Git Sync..." context menu entry to see something like the following dialog:

[[File:git_work_sync1.png]]

There are a number of ways you can synchronize your repository: The default one will be
"Pull", which is okay as long as you don't have any changes of your own. As the screenshot shows that we actually
have some changes, we want to use "Fetch&Rebase". This will cause Git to download the changes
and then start a "rebase", which we will explain in the next section.

= Rebasing your Changes =

The main idea with rebasing is to update your changes so they apply cleanly to the current state of the repository. This is important, as some parallel changes might have conflicted with what you have done.

The rebase window will come up automatically if you chose "Fetch&Rebase" in the last step,
but you can reach it manually using the "Rebase..." entry in the TortoiseGit right-click menu. It should look like follows:

[[File:git_work_rebase1.png]]

What is happening here? The idea of a rebase is simple: The listed changes have been done to
an out-of-date repository, therefore they need to be updated for the new state of the OpenClonk repository.
To do this, Git will first temporarily (!) remove your changes, then check out the new
repository state, and finally try to "replay" the changes in the list.
Pressing "Start Rebasing" starts this process, resulting in all your commits getting updated -
unless conflicts happen, which we will explain below.

== Reorganizing Changes ==

Before we get to conflicts though, note that the rebase window allows you to reorder, edit and "squash" (merge) changes.
This is Git's workflow philosophy - as rebasing means re-applying all your changes, it might
as well allow you to change and reorder them while we're at it. Let's say we want to merge the two
commits for Credits.txt. We do this by making sure that the commits appear directly after each other
in the list, then change the "REBASE" state to "Sqash" for the ''later'' commit (look at the ID if unsure):

[[File:git_work_rebase2.png]]

When we select "Start Rebasing" now, rebasing will actually suspend after the first two commits so
we can edit the message for the merged commit. By default Git will just
append the two original messages, which we most likely
want to change:

[[File:git_work_rebase3.png]]

Notice that in the list the first commit is grayed out now to signify that it has already been converted at this point, and the second commit is bold as we
are currently considering how to re-record it.
When you're finished, press "Commit" to continue and eventually finish rebasing.

== Conflicts and Editing ==

Git is pretty smart about making sense of your changes even if the repository has changed. Sometimes, though, it will still
run into a problem where it has to request your help in figuring out what to do:

[[File:git_work_rebase4.png]]

Here Git has encountered a conflict while trying to apply the bold change, in the file marked in red.
If we open the file, we might find something like follows:

<<<<<<< HEAD
LogF("WARNING: Control %s of set %s contains undefined key \"%s\".", GetControlName(), pParentSet->GetName(), szKeyName);
#endif
=======
LogF("WARNING: Control %s of set %s contains undefined key %s.", GetControlName(), pParentSet->GetName(), szKeyName);
>>>>>>> 6e29e01... Removed quotes from message

This is telling us that while our commit (6e29e01) changed these lines to something, the OpenClonk
repository (HEAD) changed them to something else. To resolve this, we update all conflicted files to the correct
state, mark the files as "Resolved" (using the right-click menu) and finally press "Commit"
in order to accept the resolution.

= Submitting your Change =

After you have rebased your changes to the current state of the OpenClonk repository (''important!'') you
can attempt to submit your changes. How you do this depends on whether you are an OpenClonk
team member or not: You either have to submit a patch, or can push the OpenClonk repository directly.
We will explain both methods here.

== Creating a Patch ==

In order to get a commit into the repository as a non-team member, you will have to send
the change to somebody that can review and accept it, for example by posting it in the forum.
The first step is to package your change as a patch file.

To do this, use the "Create Patch Serial..." or "Format Patch" option from the right-click menu
(it's the same thing, just named differently depending on where you are). You should get the
following window:

[[File:ghc_work_patch1.png]]

Make sure to select "FETCH_HEAD" in the "Since" field in order to get all patches that are
new relative to the OpenClonk repository. Otherwise, TortoiseGit can use pretty nonsensical defaults
and produce thousands of useless patches as a result.
Select a convenient directory for the patches to go into, and select "OK" to get the ball rolling.

Afterwards, you should see all your changes as conveniently-named patch files in the directory you have chosen:

[[File:ghc_work_patch2.png]]

You can send this to an OpenClonk team member - or anybody with an OpenClonk repository clone, really -
and they will be able to import your change. If they tell you that the patch doesn't apply cleanly, this probably
means that you have to synchronize and rebase again (see previous section).

== Pushing Changes ==

Pushing a change directly is slightly easier - all you have to do is select "Push" from the synchronization
window. What can happen here is that you get a message of the form:

Pushing to ssh://git@git.openclonk.org/openclonk.git
To ssh://git@git.openclonk.org/openclonk.git
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'ssh://git@git.openclonk.org/openclonk.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.

This helpful message tells you that you have forgotten to synchronize & rebase before trying to push. Better get used to it :-)

Git Workflow

2012-12-01T21:30:19Z

PeterW: Added note for how to the repository, just in case somebody lands here.

As an open source project, we want to make it easy for a lot of people to work on
our code - even people that aren't directly involved in the project!
That's why we use a distributed version control system called [http://git-scm.com/ Git],
which makes sure that all files stay consistent and it's not too easy to lose your data
when things get complicated. This article will walk you through how you can use this system
to organize and submit your changes to OpenClonk.

We will assume here that you have a clone of the OpenClonk repository like the one
you created if you followed the [[Building_with_Windows|Windows build tutorial]]. If you haven't, just follow the tutorial and return here after you have finished the "Clone" section.
The screenshots and explanations will also be somewhat specific to TortoiseGit.
On the other hand, the workflow is equally viable no matter what Git interface you use.

= Committing your Changes =

The first step is to actually make some meaningful changes to OpenClonk.
TortoiseGit will detect your work and automatically mark files or directories that have changed:

[[File:git_work_commit1.png]]

To register your changes with Git, you need to "commit" them using the "Git Commit" entry from the right-click menu.
Here you can select what files you want to include in the commit, and give a message
describing what you have done. Try to give a short summary of the change in the first
line, followed by more details and explanations after one empty line.

[[File:git_work_commit2.png]]

It is generally a good idea to commit early, as registering changes with Git means they will be a lot harder to lose.
It's a good idea to do this even if you know that you will want to do additional changes to the commit later:
The commit window allows you to "amend" the last commit so you
can keep working on it.

For even more flexibility, simply create another
commit for additional changes and [[#Reorganizing Changes|"squash" them later]]. This is also a good idea because it allows
you to go back and forth between revisions until you are convinced that your change works. It might even be
a good idea to mark commits that you want to be merged with a marker like "[squash!]" so
you don't forget to merge the changes later on.

= Synchronizing your Repository =

OpenClonk is under constant development, and it's generally a good idea to stay up-to-date.
Maybe uninuitively, this is especially vital if you are thinking of submitting a change:
You need to make sure that your changes work with where development is currently at.

Use the "Git Sync..." context menu entry to see something like the following dialog:

[[File:git_work_sync1.png]]

There are a number of ways you can synchronize your repository: The default one will be
"Pull", which is okay as long as you don't have any changes of your own. As the screenshot shows that we actually
have some changes, we want to use "Fetch&Rebase". This will cause Git to download the changes
and then start a "rebase", which we will explain in the next section.

= Rebasing your Changes =

The main idea with rebasing is to update your changes so they apply cleanly to the current state of the repository. This is important, as some parallel changes might have conflicted with what you have done.

The rebase window will come up automatically if you chose "Fetch&Rebase" in the last step,
but you can reach it manually using the "Rebase..." entry in the TortoiseGit right-click menu. It should look like follows:

[[File:git_work_rebase1.png]]

What is happening here? The idea of a rebase is simple: The listed changes have been done to
an out-of-date repository, therefore they need to be updated for the new state of the OpenClonk repository.
To do this, Git will first temporarily (!) remove your changes, then check out the new
repository state, and finally try to "replay" the changes in the list.
Pressing "Start Rebasing" starts this process, resulting in all your commits getting updated -
unless conflicts happen, which we will explain below.

== Reorganizing Changes ==

Before we get to conflicts though, note that the rebase window allows you to reorder, edit and "squash" (merge) changes.
This is Git's workflow philosophy - as rebasing means re-applying all your changes, it might
as well allow you to change and reorder them while we're at it. Let's say we want to merge the two
commits for Credits.txt. We do this by making sure that the commits appear directly after each other
in the list, then change the "REBASE" state to "Sqash" for the ''later'' commit (look at the ID if unsure):

[[File:git_work_rebase2.png]]

When we select "Start Rebasing" now, rebasing will actually suspend after the first two commits so
we can edit the message for the merged commit. By default Git will just
append the two original messages, which we most likely
want to change:

[[File:git_work_rebase3.png]]

Notice that in the list the first commit is grayed out now to signify that it has already been converted at this point, and the second commit is bold as we
are currently considering how to re-record it.
When you're finished, press "Commit" to continue and eventually finish rebasing.

== Conflicts and Editing ==

Git is pretty smart about making sense of your changes even if the repository has changed. Sometimes, though, it will still
run into a problem where it has to request your help in figuring out what to do:

[[File:git_work_rebase4.png]]

Here Git has encountered a conflict while trying to apply the bold change, in the file marked in red.
If we open the file, we might find something like follows:

<<<<<<< HEAD
LogF("WARNING: Control %s of set %s contains undefined key \"%s\".", GetControlName(), pParentSet->GetName(), szKeyName);
#endif
=======
LogF("WARNING: Control %s of set %s contains undefined key %s.", GetControlName(), pParentSet->GetName(), szKeyName);
>>>>>>> 6e29e01... Removed quotes from message

This is telling us that while our commit (6e29e01) changed these lines to something, the OpenClonk
repository (HEAD) changed them to something else. To resolve this, we update all conflicted files to the correct
state, mark the files as "Resolved" (using the right-click menu) and finally press "Commit"
in order to accept the resolution.

= Submitting your Change =

After you have rebased your changes to the current state of the OpenClonk repository (''important!'') you
can attempt to submit your changes. How you do this depends on whether you are an OpenClonk
team member or not: You either have to submit a patch, or can push the OpenClonk repository directly.
We will explain both methods here.

== Creating a Patch ==

In order to get a commit into the repository as a non-team member, you will have to send
the change to somebody that can review and accept it, for example by posting it in the forum.
The first step is to package your change as a patch file.

To do this, use the "Create Patch Serial..." or "Format Patch" option from the right-click menu
(it's the same thing, just named differently depending on where you are). You should get the
following window:

[[File:ghc_work_patch1.png]]

Make sure you should select "FETCH_HEAD" in the "Since" field in order to get all patches that are
new relative to the OpenClonk repository. Otherwise, TortoiseGit can use pretty nonsensical defaults
and produce thousands of useless patches as a result.
Select a convenient directory for the patches to go into, and select "OK" to get the ball rolling.

Afterwards, you should see all your changes as conveniently-named patch files in the directory you have chosen:

[[File:ghc_work_patch2.png]]

You can send this to an OpenClonk team member - or anybody with an OpenClonk repository clone, really -
and they will be able to import your change. If they tell you that the patch doesn't apply cleanly, this probably
means that you have to synchronize and rebase again (see previous section).

== Pushing Changes ==

Pushing a change directly is slightly easier - all you have to do is select "Push" from the synchronization
window. What can happen here is that you get a message of the form:

Pushing to ssh://git@git.openclonk.org/openclonk.git
To ssh://git@git.openclonk.org/openclonk.git
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'ssh://git@git.openclonk.org/openclonk.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.

This helpful message tells you that you have forgotten to synchronize & rebase before trying to push. Better get used to it :-)

Development

2012-12-01T21:28:15Z

PeterW: Git workflow links

__NOTOC__

OpenClonk is an open project. That means it depends on people coming in and helping out. People just like you! This page should give you an idea what you could do in order to get involved.

=== Use Development Snapshots ===

OpenClonk is continously in development. The "current" version can change daily! If you want to follow the development, it is a good idea to make sure you are able to run development versions. You will not need to build them yourself - just use the development snapshots linked below and you should be ready to go.

* Development Snapshots - [http://www.openclonk.org/nightly-builds/ www.openclonk.org/nightly-builds/]
* Blog - [http://blog.openclonk.org blog.openclonk.org]
* Changelog - [http://hg.openclonk.org/openclonk/ hg.openclonk.org/openclonk/]
* Browse source - [http://hg.openclonk.org/openclonk/file/ hg.openclonk.org/openclonk/file/]

=== Report Bugs ===

We cannot possibly account for every possible configuration out there. If you see something that's wrong, we would really like to know about it. Especially if you are willing to actively work with us in finding a solution for the problem.

Here's how you can reach us:

* IRC - [irc://irc.euirc.net/openclonk-dev/ #openclonk-dev] on irc.euirc.net (Problems connecting? Use irc.ham.de.euirc.net)
* Bugtracker - [http://bugs.openclonk.org bugs.openclonk.org]
* Forum - [http://forum.openclonk.org forum.openclonk.org]

=== Contribute Scripts or Game Content ===

Just like Clonk Rage before, most things in OpenClonk can be changed without touching the engine. Instead, we rely on a script language and a flexible game content system to make up our game content. This means that you can get involved easily - without having to learn C++ first! Traditionally, developing own objects and scenarios and sharing them with others has been how pretty much all of today's developers started out.

* Developer Documentation [http://docs.openclonk.org/en/sdk/ docs.openclonk.org/en/sdk/]
* Forum - [http://forum.openclonk.org forum.openclonk.org]
* Style Guide - [http://wiki.openclonk.org/w/C4Script_Style_Guidelines wiki.openclonk.org/w/C4Script_Style_Guidelines]
* Contribute changes - [[Git Workflow]]

=== Build OpenClonk Yourself ===

When delving deeper into OpenClonk, you will often find yourself in the situation that you need a closer look at what makes OpenClonk tick internally. At that point, it is a good idea to assume the perspective of developers - get the source code and build it in your own development environment.

* Tutorial for Windows - [http://wiki.openclonk.org/w/Building_with_Windows wiki.openclonk.org/w/Building_with_Windows]
* General instructions - [http://wiki.openclonk.org/w/Build_OpenClonk wiki.openclonk.org/w/Build_OpenClonk]
* Mercurial Guide - [http://wiki.openclonk.org/w/Mercurial_Guide wiki.openclonk.org/w/Mercurial_Guide]
* Mercurial Repository - [http://hg.openclonk.org/openclonk/ hg.openclonk.org/openclonk/]
* Source Code Structure - [http://wiki.openclonk.org/w/Source_code_structure wiki.openclonk.org/w/Source_code_structure]

=== Hack the OpenClonk Engine ===

Maybe you already are well-versed in C++ and want to help out actually diagnosing problems? Or - even better - have your own ideas on engine improvements? We are always glad to look at patches.

* Wondering where to start? - [[GSoC2011Ideas|Ideas page]]
* Debugging synchronization losses - [http://wiki.openclonk.org/w/Sync_losses wiki.openclonk.org/w/Sync_Losses]
* Style Guide - [http://wiki.openclonk.org/w/Style_Guidelines wiki.openclonk.org/w/Style_Guidelines]
* Forum, developers' corner - [http://forum.openclonk.org/board_show.pl?bid=5 forum.openclonk.org]
* Contribute changes - [[Git Workflow]]

=== Legal Stuff ===

OpenClonk uses the ISC license for code (engine and script) and CC-by for most other media. Read more about the [[License | license stuff]] here.

Building with Windows

2012-12-01T21:25:06Z

PeterW: Workflow links

= 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 [[Git Workflow|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 [http://code.google.com/p/tortoisegit/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

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:

[[File:build_windows_tgit2.png|860px]]

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

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

[[File:build_windows_tgit4.png]]

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the [http://code.google.com/p/msysgit/downloads/list?can=2&q=%22Full+installer+for+official+Git+for+Windows%22 "Full installer for official Git"] link will get you to another download page:

[[File:build_windows_tgit3.png|860px]]

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:

[[File: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.

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

[[File: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 "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.

[[File:build_windows_tgit_pub.png]]

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!

[[File:build_windows_tgit_finish.png]]

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 [http://docs.openclonk.org/en/sdk/ 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 [http://www.microsoft.com/express/vc/#webInstall 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:

[[File:build_windows_msvc1_new.png|860px]]

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_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]]

== 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 [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

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 [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File: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.

[[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 10". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.

[[File: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:

[[File:build_windows_build1.png]]

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

[[File:build_windows_build2.png]]

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

[[File:build_windows_build3.png]]

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.

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

Git Workflow

2012-12-01T21:10:10Z

PeterW: /* Creating a Patch */

As an open source project, we want to make it easy for a lot of people to work on
our code - even people that aren't directly involved in the project!
That's why we use a distributed version control system called [http://git-scm.com/ Git],
which makes sure that all files stay consistent and it's not too easy to lose your data
when things get complicated. This article will walk you through how you can use this system
to organize and submit your changes to OpenClonk.

We will assume here that you have a clone of the OpenClonk repository like the one
you created if you followed the [[Building_with_Windows|Windows build tutorial]].
The screenshots and explanations will also be somewhat specific to TortoiseGit.
On the other hand, the workflow is equally viable no matter what Git interface you use.

= Committing your Changes =

The first step is to actually make some meaningful changes to OpenClonk.
TortoiseGit will detect your work and automatically mark files or directories that have changed:

[[File:git_work_commit1.png]]

To register your changes with Git, you need to "commit" them using the "Git Commit" entry from the right-click menu.
Here you can select what files you want to include in the commit, and give a message
describing what you have done. Try to give a short summary of the change in the first
line, followed by more details and explanations after one empty line.

[[File:git_work_commit2.png]]

It is generally a good idea to commit early, as registering changes with Git means they will be a lot harder to lose.
It's a good idea to do this even if you know that you will want to do additional changes to the commit later:
The commit window allows you to "amend" the last commit so you
can keep working on it.

For even more flexibility, simply create another
commit for additional changes and [[#Reorganizing Changes|"squash" them later]]. This is also a good idea because it allows
you to go back and forth between revisions until you are convinced that your change works. It might even be
a good idea to mark commits that you want to be merged with a marker like "[squash!]" so
you don't forget to merge the changes later on.

= Synchronizing your Repository =

OpenClonk is under constant development, and it's generally a good idea to stay up-to-date.
Maybe uninuitively, this is especially vital if you are thinking of submitting a change:
You need to make sure that your changes work with where development is currently at.

Use the "Git Sync..." context menu entry to see something like the following dialog:

[[File:git_work_sync1.png]]

There are a number of ways you can synchronize your repository: The default one will be
"Pull", which is okay as long as you don't have any changes of your own. As the screenshot shows that we actually
have some changes, we want to use "Fetch&Rebase". This will cause Git to download the changes
and then start a "rebase", which we will explain in the next section.

= Rebasing your Changes =

The main idea with rebasing is to update your changes so they apply cleanly to the current state of the repository. This is important, as some parallel changes might have conflicted with what you have done.

The rebase window will come up automatically if you chose "Fetch&Rebase" in the last step,
but you can reach it manually using the "Rebase..." entry in the TortoiseGit right-click menu. It should look like follows:

[[File:git_work_rebase1.png]]

What is happening here? The idea of a rebase is simple: The listed changes have been done to
an out-of-date repository, therefore they need to be updated for the new state of the OpenClonk repository.
To do this, Git will first temporarily (!) remove your changes, then check out the new
repository state, and finally try to "replay" the changes in the list.
Pressing "Start Rebasing" starts this process, resulting in all your commits getting updated -
unless conflicts happen, which we will explain below.

== Reorganizing Changes ==

Before we get to conflicts though, note that the rebase window allows you to reorder, edit and "squash" (merge) changes.
This is Git's workflow philosophy - as rebasing means re-applying all your changes, it might
as well allow you to change and reorder them while we're at it. Let's say we want to merge the two
commits for Credits.txt. We do this by making sure that the commits appear directly after each other
in the list, then change the "REBASE" state to "Sqash" for the ''later'' commit (look at the ID if unsure):

[[File:git_work_rebase2.png]]

When we select "Start Rebasing" now, rebasing will actually suspend after the first two commits so
we can edit the message for the merged commit. By default Git will just
append the two original messages, which we most likely
want to change:

[[File:git_work_rebase3.png]]

Notice that in the list the first commit is grayed out now to signify that it has already been converted at this point, and the second commit is bold as we
are currently considering how to re-record it.
When you're finished, press "Commit" to continue and eventually finish rebasing.

== Conflicts and Editing ==

Git is pretty smart about making sense of your changes even if the repository has changed. Sometimes, though, it will still
run into a problem where it has to request your help in figuring out what to do:

[[File:git_work_rebase4.png]]

Here Git has encountered a conflict while trying to apply the bold change, in the file marked in red.
If we open the file, we might find something like follows:

<<<<<<< HEAD
LogF("WARNING: Control %s of set %s contains undefined key \"%s\".", GetControlName(), pParentSet->GetName(), szKeyName);
#endif
=======
LogF("WARNING: Control %s of set %s contains undefined key %s.", GetControlName(), pParentSet->GetName(), szKeyName);
>>>>>>> 6e29e01... Removed quotes from message

This is telling us that while our commit (6e29e01) changed these lines to something, the OpenClonk
repository (HEAD) changed them to something else. To resolve this, we update all conflicted files to the correct
state, mark the files as "Resolved" (using the right-click menu) and finally press "Commit"
in order to accept the resolution.

= Submitting your Change =

After you have rebased your changes to the current state of the OpenClonk repository (''important!'') you
can attempt to submit your changes. How you do this depends on whether you are an OpenClonk
team member or not: You either have to submit a patch, or can push the OpenClonk repository directly.
We will explain both methods here.

== Creating a Patch ==

In order to get a commit into the repository as a non-team member, you will have to send
the change to somebody that can review and accept it, for example by posting it in the forum.
The first step is to package your change as a patch file.

To do this, use the "Create Patch Serial..." or "Format Patch" option from the right-click menu
(it's the same thing, just named differently depending on where you are). You should get the
following window:

[[File:ghc_work_patch1.png]]

Make sure you should select "FETCH_HEAD" in the "Since" field in order to get all patches that are
new relative to the OpenClonk repository. Otherwise, TortoiseGit can use pretty nonsensical defaults
and produce thousands of useless patches as a result.
Select a convenient directory for the patches to go into, and select "OK" to get the ball rolling.

Afterwards, you should see all your changes as conveniently-named patch files in the directory you have chosen:

[[File:ghc_work_patch2.png]]

You can send this to an OpenClonk team member - or anybody with an OpenClonk repository clone, really -
and they will be able to import your change. If they tell you that the patch doesn't apply cleanly, this probably
means that you have to synchronize and rebase again (see previous section).

== Pushing Changes ==

Pushing a change directly is slightly easier - all you have to do is select "Push" from the synchronization
window. What can happen here is that you get a message of the form:

Pushing to ssh://git@git.openclonk.org/openclonk.git
To ssh://git@git.openclonk.org/openclonk.git
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'ssh://git@git.openclonk.org/openclonk.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.

This helpful message tells you that you have forgotten to synchronize & rebase before trying to push. Better get used to it :-)

Git Workflow

2012-12-01T21:07:51Z

PeterW: /* Reorganizing Changes */

As an open source project, we want to make it easy for a lot of people to work on
our code - even people that aren't directly involved in the project!
That's why we use a distributed version control system called [http://git-scm.com/ Git],
which makes sure that all files stay consistent and it's not too easy to lose your data
when things get complicated. This article will walk you through how you can use this system
to organize and submit your changes to OpenClonk.

We will assume here that you have a clone of the OpenClonk repository like the one
you created if you followed the [[Building_with_Windows|Windows build tutorial]].
The screenshots and explanations will also be somewhat specific to TortoiseGit.
On the other hand, the workflow is equally viable no matter what Git interface you use.

= Committing your Changes =

The first step is to actually make some meaningful changes to OpenClonk.
TortoiseGit will detect your work and automatically mark files or directories that have changed:

[[File:git_work_commit1.png]]

To register your changes with Git, you need to "commit" them using the "Git Commit" entry from the right-click menu.
Here you can select what files you want to include in the commit, and give a message
describing what you have done. Try to give a short summary of the change in the first
line, followed by more details and explanations after one empty line.

[[File:git_work_commit2.png]]

It is generally a good idea to commit early, as registering changes with Git means they will be a lot harder to lose.
It's a good idea to do this even if you know that you will want to do additional changes to the commit later:
The commit window allows you to "amend" the last commit so you
can keep working on it.

For even more flexibility, simply create another
commit for additional changes and [[#Reorganizing Changes|"squash" them later]]. This is also a good idea because it allows
you to go back and forth between revisions until you are convinced that your change works. It might even be
a good idea to mark commits that you want to be merged with a marker like "[squash!]" so
you don't forget to merge the changes later on.

= Synchronizing your Repository =

OpenClonk is under constant development, and it's generally a good idea to stay up-to-date.
Maybe uninuitively, this is especially vital if you are thinking of submitting a change:
You need to make sure that your changes work with where development is currently at.

Use the "Git Sync..." context menu entry to see something like the following dialog:

[[File:git_work_sync1.png]]

There are a number of ways you can synchronize your repository: The default one will be
"Pull", which is okay as long as you don't have any changes of your own. As the screenshot shows that we actually
have some changes, we want to use "Fetch&Rebase". This will cause Git to download the changes
and then start a "rebase", which we will explain in the next section.

= Rebasing your Changes =

The main idea with rebasing is to update your changes so they apply cleanly to the current state of the repository. This is important, as some parallel changes might have conflicted with what you have done.

The rebase window will come up automatically if you chose "Fetch&Rebase" in the last step,
but you can reach it manually using the "Rebase..." entry in the TortoiseGit right-click menu. It should look like follows:

[[File:git_work_rebase1.png]]

What is happening here? The idea of a rebase is simple: The listed changes have been done to
an out-of-date repository, therefore they need to be updated for the new state of the OpenClonk repository.
To do this, Git will first temporarily (!) remove your changes, then check out the new
repository state, and finally try to "replay" the changes in the list.
Pressing "Start Rebasing" starts this process, resulting in all your commits getting updated -
unless conflicts happen, which we will explain below.

== Reorganizing Changes ==

Before we get to conflicts though, note that the rebase window allows you to reorder, edit and "squash" (merge) changes.
This is Git's workflow philosophy - as rebasing means re-applying all your changes, it might
as well allow you to change and reorder them while we're at it. Let's say we want to merge the two
commits for Credits.txt. We do this by making sure that the commits appear directly after each other
in the list, then change the "REBASE" state to "Sqash" for the ''later'' commit (look at the ID if unsure):

[[File:git_work_rebase2.png]]

When we select "Start Rebasing" now, rebasing will actually suspend after the first two commits so
we can edit the message for the merged commit. By default Git will just
append the two original messages, which we most likely
want to change:

[[File:git_work_rebase3.png]]

Notice that in the list the first commit is grayed out now to signify that it has already been converted at this point, and the second commit is bold as we
are currently considering how to re-record it.
When you're finished, press "Commit" to continue and eventually finish rebasing.

== Conflicts and Editing ==

Git is pretty smart about making sense of your changes even if the repository has changed. Sometimes, though, it will still
run into a problem where it has to request your help in figuring out what to do:

[[File:git_work_rebase4.png]]

Here Git has encountered a conflict while trying to apply the bold change, in the file marked in red.
If we open the file, we might find something like follows:

<<<<<<< HEAD
LogF("WARNING: Control %s of set %s contains undefined key \"%s\".", GetControlName(), pParentSet->GetName(), szKeyName);
#endif
=======
LogF("WARNING: Control %s of set %s contains undefined key %s.", GetControlName(), pParentSet->GetName(), szKeyName);
>>>>>>> 6e29e01... Removed quotes from message

This is telling us that while our commit (6e29e01) changed these lines to something, the OpenClonk
repository (HEAD) changed them to something else. To resolve this, we update all conflicted files to the correct
state, mark the files as "Resolved" (using the right-click menu) and finally press "Commit"
in order to accept the resolution.

= Submitting your Change =

After you have rebased your changes to the current state of the OpenClonk repository (''important!'') you
can attempt to submit your changes. How you do this depends on whether you are an OpenClonk
team member or not: You either have to submit a patch, or can push the OpenClonk repository directly.
We will explain both methods here.

== Creating a Patch ==

In order to get a commit into the repository as a non-team member, you will have to send
the change to somebody that can review and accept it, for example by posting it in the forum.
The first step is to package your change as a patch file.

To do this, use the "Create Patch Serial..." or "Format Patch" option from the right-click menu
(it's the same thing, just named differently depending on where you are). You should get the
following window:

[[File:git_work_patch1.png]]

Make sure you should select "FETCH_HEAD" in the "Since" field in order to get all patches that are
new relative to the OpenClonk repository. Otherwise, TortoiseGit can use pretty nonsensical defaults
and produce thousands of useless patches as a result.
Select a convenient directory for the patches to go into, and select "OK" to get the ball rolling.

Afterwards, you should see all your changes as conveniently-named patch files in the directory you have chosen:

[[File:git_work_patch2.png]]

You can send this to an OpenClonk team member - or anybody with an OpenClonk repository clone, really -
and they will be able to import your change. If they tell you that the patch doesn't apply cleanly, this probably
means that you have to synchronize and rebase again (see previous section).

== Pushing Changes ==

Pushing a change directly is slightly easier - all you have to do is select "Push" from the synchronization
window. What can happen here is that you get a message of the form:

Pushing to ssh://git@git.openclonk.org/openclonk.git
To ssh://git@git.openclonk.org/openclonk.git
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'ssh://git@git.openclonk.org/openclonk.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.

This helpful message tells you that you have forgotten to synchronize & rebase before trying to push. Better get used to it :-)

File:Git work sync1.png

2012-12-01T21:05:01Z

PeterW:

File:Git work rebase4.png

2012-12-01T21:04:55Z

PeterW:

File:Git work rebase3.png

2012-12-01T21:04:48Z

PeterW:

File:Git work rebase2.png

2012-12-01T21:04:42Z

PeterW:

File:Git work rebase1.png

2012-12-01T21:04:35Z

PeterW:

File:Git work commit2.png

2012-12-01T21:04:28Z

PeterW:

File:Git work commit1.png

2012-12-01T21:04:18Z

PeterW:

File:Ghc work patch2.png

2012-12-01T21:04:08Z

PeterW:

File:Ghc work patch1.png

2012-12-01T21:03:58Z

PeterW:

Git Workflow

2012-12-01T20:58:35Z

PeterW: Simple Git Workflow Guide

As an open source project, we want to make it easy for a lot of people to work on
our code - even people that aren't directly involved in the project!
That's why we use a distributed version control system called [http://git-scm.com/ Git],
which makes sure that all files stay consistent and it's not too easy to lose your data
when things get complicated. This article will walk you through how you can use this system
to organize and submit your changes to OpenClonk.

We will assume here that you have a clone of the OpenClonk repository like the one
you created if you followed the [[Building_with_Windows|Windows build tutorial]].
The screenshots and explanations will also be somewhat specific to TortoiseGit.
On the other hand, the workflow is equally viable no matter what Git interface you use.

= Committing your Changes =

The first step is to actually make some meaningful changes to OpenClonk.
TortoiseGit will detect your work and automatically mark files or directories that have changed:

[[File:git_work_commit1.png]]

To register your changes with Git, you need to "commit" them using the "Git Commit" entry from the right-click menu.
Here you can select what files you want to include in the commit, and give a message
describing what you have done. Try to give a short summary of the change in the first
line, followed by more details and explanations after one empty line.

[[File:git_work_commit2.png]]

It is generally a good idea to commit early, as registering changes with Git means they will be a lot harder to lose.
It's a good idea to do this even if you know that you will want to do additional changes to the commit later:
The commit window allows you to "amend" the last commit so you
can keep working on it.

For even more flexibility, simply create another
commit for additional changes and [[#Reorganizing Changes|"squash" them later]]. This is also a good idea because it allows
you to go back and forth between revisions until you are convinced that your change works. It might even be
a good idea to mark commits that you want to be merged with a marker like "[squash!]" so
you don't forget to merge the changes later on.

= Synchronizing your Repository =

OpenClonk is under constant development, and it's generally a good idea to stay up-to-date.
Maybe uninuitively, this is especially vital if you are thinking of submitting a change:
You need to make sure that your changes work with where development is currently at.

Use the "Git Sync..." context menu entry to see something like the following dialog:

[[File:git_work_sync1.png]]

There are a number of ways you can synchronize your repository: The default one will be
"Pull", which is okay as long as you don't have any changes of your own. As the screenshot shows that we actually
have some changes, we want to use "Fetch&Rebase". This will cause Git to download the changes
and then start a "rebase", which we will explain in the next section.

= Rebasing your Changes =

The main idea with rebasing is to update your changes so they apply cleanly to the current state of the repository. This is important, as some parallel changes might have conflicted with what you have done.

The rebase window will come up automatically if you chose "Fetch&Rebase" in the last step,
but you can reach it manually using the "Rebase..." entry in the TortoiseGit right-click menu. It should look like follows:

[[File:git_work_rebase1.png]]

What is happening here? The idea of a rebase is simple: The listed changes have been done to
an out-of-date repository, therefore they need to be updated for the new state of the OpenClonk repository.
To do this, Git will first temporarily (!) remove your changes, then check out the new
repository state, and finally try to "replay" the changes in the list.
Pressing "Start Rebasing" starts this process, resulting in all your commits getting updated -
unless conflicts happen, which we will explain below.

== Reorganizing Changes ==

Before we get to conflicts though, note that the rebase window allows you to reorder, edit and "squash" (merge) changes.
This is Git's workflow philosophy - as rebasing means re-applying all your changes, it might
as well allow you to change and reorder them while we're at it. Let's say we want to merge the two
commits for Credits.txt. We do this by making sure that the commits appear directly after each other
in the list, then change the "REBASE" state to "Sqash" for the ''later'' commit (look at the ID if unsure):

[[File:git_work_rebase2.png]]

When we select "Start Rebasing" now, rebasing will actually suspend after the first two commits so
we can edit the message for the merged commit. By default Git will just
append the two original messages, which we most likely
want to change:

[[File:git_work_rebase3.png]]

Notice that in the list the first commit is grayed out now to signify that it has already been converted at this point, and the second commit is bold as we
are currently considering how to add it.
When you're finished, press "Commit" to continue and eventually finish rebasing.

== Conflicts and Editing ==

Git is pretty smart about making sense of your changes even if the repository has changed. Sometimes, though, it will still
run into a problem where it has to request your help in figuring out what to do:

[[File:git_work_rebase4.png]]

Here Git has encountered a conflict while trying to apply the bold change, in the file marked in red.
If we open the file, we might find something like follows:

<<<<<<< HEAD
LogF("WARNING: Control %s of set %s contains undefined key \"%s\".", GetControlName(), pParentSet->GetName(), szKeyName);
#endif
=======
LogF("WARNING: Control %s of set %s contains undefined key %s.", GetControlName(), pParentSet->GetName(), szKeyName);
>>>>>>> 6e29e01... Removed quotes from message

This is telling us that while our commit (6e29e01) changed these lines to something, the OpenClonk
repository (HEAD) changed them to something else. To resolve this, we update all conflicted files to the correct
state, mark the files as "Resolved" (using the right-click menu) and finally press "Commit"
in order to accept the resolution.

= Submitting your Change =

After you have rebased your changes to the current state of the OpenClonk repository (''important!'') you
can attempt to submit your changes. How you do this depends on whether you are an OpenClonk
team member or not: You either have to submit a patch, or can push the OpenClonk repository directly.
We will explain both methods here.

== Creating a Patch ==

In order to get a commit into the repository as a non-team member, you will have to send
the change to somebody that can review and accept it, for example by posting it in the forum.
The first step is to package your change as a patch file.

To do this, use the "Create Patch Serial..." or "Format Patch" option from the right-click menu
(it's the same thing, just named differently depending on where you are). You should get the
following window:

[[File:git_work_patch1.png]]

Make sure you should select "FETCH_HEAD" in the "Since" field in order to get all patches that are
new relative to the OpenClonk repository. Otherwise, TortoiseGit can use pretty nonsensical defaults
and produce thousands of useless patches as a result.
Select a convenient directory for the patches to go into, and select "OK" to get the ball rolling.

Afterwards, you should see all your changes as conveniently-named patch files in the directory you have chosen:

[[File:git_work_patch2.png]]

You can send this to an OpenClonk team member - or anybody with an OpenClonk repository clone, really -
and they will be able to import your change. If they tell you that the patch doesn't apply cleanly, this probably
means that you have to synchronize and rebase again (see previous section).

== Pushing Changes ==

Pushing a change directly is slightly easier - all you have to do is select "Push" from the synchronization
window. What can happen here is that you get a message of the form:

Pushing to ssh://git@git.openclonk.org/openclonk.git
To ssh://git@git.openclonk.org/openclonk.git
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'ssh://git@git.openclonk.org/openclonk.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Merge the remote changes (e.g. 'git pull')
hint: before pushing again.

This helpful message tells you that you have forgotten to synchronize & rebase before trying to push. Better get used to it :-)

Building with Windows

2012-12-01T17:38:22Z

PeterW:

= 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 [http://code.google.com/p/tortoisegit/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

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:

[[File:build_windows_tgit2.png|860px]]

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

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

[[File:build_windows_tgit4.png]]

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the [http://code.google.com/p/msysgit/downloads/list?can=2&q=%22Full+installer+for+official+Git+for+Windows%22 "Full installer for official Git"] link will get you to another download page:

[[File:build_windows_tgit3.png|860px]]

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:

[[File: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.

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

[[File: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 "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.

[[File:build_windows_tgit_pub.png]]

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!

[[File:build_windows_tgit_finish.png]]

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 [http://docs.openclonk.org/en/sdk/ 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 [http://www.microsoft.com/express/vc/#webInstall 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:

[[File:build_windows_msvc1_new.png|860px]]

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_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]]

== 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 [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

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 [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File: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.

[[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 10". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.

[[File: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:

[[File:build_windows_build1.png]]

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

[[File:build_windows_build2.png]]

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

[[File:build_windows_build3.png]]

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.

[[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

2012-12-01T17:36:47Z

PeterW: Reword a bit to make the PuTTY remark less confusing

= 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 [http://code.google.com/p/tortoisegit/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

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:

[[File:build_windows_tgit2.png|860px]]

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

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

[[File:build_windows_tgit4.png]]

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the [http://code.google.com/p/msysgit/downloads/list?can=2&q=%22Full+installer+for+official+Git+for+Windows%22 "Full installer for official Git"] link will get you to another download page:

[[File:build_windows_tgit3.png|860px]]

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:

[[File: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.

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

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

[[File:build_windows_tgit_pub.png]]

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!

[[File:build_windows_tgit_finish.png]]

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 [http://docs.openclonk.org/en/sdk/ 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 [http://www.microsoft.com/express/vc/#webInstall 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:

[[File:build_windows_msvc1_new.png|860px]]

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_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]]

== 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 [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

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 [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File: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.

[[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 10". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.

[[File: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:

[[File:build_windows_build1.png]]

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

[[File:build_windows_build2.png]]

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

[[File:build_windows_build3.png]]

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.

[[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

2012-11-29T12:06:40Z

PeterW:

= 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 [http://code.google.com/p/tortoisegit/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

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:

[[File:build_windows_tgit2.png|860px]]

And walk through the installation. If you are a developer and want to use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY], make sure to select the appropriate option along the way. But selecting default options everywhere won't break anything either...

[[File:build_windows_tgit4.png]]

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the [http://code.google.com/p/msysgit/downloads/list?can=2&q=%22Full+installer+for+official+Git+for+Windows%22 "Full installer for official Git"] link will get you to another download page:

[[File:build_windows_tgit3.png|860px]]

This installation will ask even more confusing questions - again developers might want to point it towards PuTTY at one point. But again default options won't cause anything to break, I would just recommend deactivating some GUI options, as TortoiseGit already offers them:

[[File: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.

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

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

[[File:build_windows_tgit_pub.png]][[File:build_windows_tgit_dev.png]]

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!

[[File:build_windows_tgit_finish.png]]

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 [http://docs.openclonk.org/en/sdk/ 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 [http://www.microsoft.com/express/vc/#webInstall 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:

[[File:build_windows_msvc1_new.png|860px]]

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_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]]

== 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 [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

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 [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File: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.

[[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 10". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.

[[File: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:

[[File:build_windows_build1.png]]

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

[[File:build_windows_build2.png]]

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

[[File:build_windows_build3.png]]

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.

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

File:Build windows tgit finish.png

2012-11-29T12:03:00Z

PeterW:

File:Build windows tgit working.png

2012-11-29T12:02:15Z

PeterW:

File:Build windows tgit dev.png

2012-11-29T12:01:36Z

PeterW:

File:Build windows tgit pub.png

2012-11-29T12:01:26Z

PeterW:

Building with Windows

2012-11-29T12:00:56Z

PeterW: /* Get the sources */

= 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 TortoiseHg ==

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 [http://code.google.com/p/tortoisegit/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

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:

[[File:build_windows_tgit2.png|860px]]

And walk through the installation. If you are a developer and want to use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY], make sure to select the appropriate option along the way. But selecting default options everywhere won't break anything either...

[[File:build_windows_tgit4.png]]

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the [http://code.google.com/p/msysgit/downloads/list?can=2&q=%22Full+installer+for+official+Git+for+Windows%22 "Full installer for official Git"] link will get you to another download page:

[[File:build_windows_tgit3.png|860px]]

This installation will ask even more confusing questions - again developers might want to point it towards PuTTY at one point. But again default options won't cause anything to break, I would just recommend deactivating some GUI options, as TortoiseGit already offers them:

[[File: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.

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

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

[[File:build_windows_tgit_pub.png]][[File:build_windows_tgit_dev.png]]

After pressing "OK", TortoiseHg 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!

[[File:build_windows_tgit_finish.png]]

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 [http://docs.openclonk.org/en/sdk/ 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 [http://www.microsoft.com/express/vc/#webInstall 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:

[[File:build_windows_msvc1_new.png|860px]]

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_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]]

== 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 [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

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 [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File: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.

[[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 10". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.

[[File: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:

[[File:build_windows_build1.png]]

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

[[File:build_windows_build2.png]]

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

[[File:build_windows_build3.png]]

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.

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

File:Build windows msvc1 new.png

2012-11-29T12:00:03Z

PeterW: uploaded a new version of "File:Build windows msvc1 new.png"

Building with Windows

2012-11-29T11:58:30Z

PeterW: /* Get Microsoft Visual Studio */

= 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 TortoiseHg ==

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 [http://code.google.com/p/tortoisegit/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

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:

[[File:build_windows_tgit2.png]]

And walk through the installation. If you are a developer and want to use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY], make sure to select the appropriate option along the way. But selecting default options everywhere won't break anything either...

[[File:build_windows_tgit4.png]]

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the [http://code.google.com/p/msysgit/downloads/list?can=2&q=%22Full+installer+for+official+Git+for+Windows%22 "Full installer for official Git"] link will get you to another download page:

[[File:build_windows_tgit3.png]]

This installation will ask even more confusing questions - again developers might want to point it towards PuTTY at one point. But again default options won't cause anything to break, I would just recommend deactivating some GUI options, as TortoiseGit already offers them:

[[File: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.

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

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

[[File:build_windows_tgit_pub.png]][[File:build_windows_tgit_dev.png]]

After pressing "OK", TortoiseHg 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!

[[File:build_windows_tgit_finish.png]]

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 [http://docs.openclonk.org/en/sdk/ 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 [http://www.microsoft.com/express/vc/#webInstall 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:

[[File:build_windows_msvc1_new.png|860px]]

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_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]]

== 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 [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

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 [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File: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.

[[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 10". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.

[[File: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:

[[File:build_windows_build1.png]]

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

[[File:build_windows_build2.png]]

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

[[File:build_windows_build3.png]]

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.

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

File:Build windows tgit6.png

2012-11-29T11:56:44Z

PeterW:

File:Build windows tgit5.png

2012-11-29T11:56:34Z

PeterW: