Developing Oolite

Overview

This page intends to allow you to setup an environment to develop Oolite. It is possible either to setup your own branch on github, or to only clone locally the master branch. In both cases, you can hack, try, do whatever takes your fancy :-) But to have your changes integrated back into the main Oolite, it is easier to setup your own branch. Luckily, you can do this at the end when you are ready to propose your code too.

Versioning (optional)

When developing software, each little modification is tracked independently and assigned a version identifier. That's called versioning. To do this, we use the git software.

The Oolite code is hosted on a git-friendly repository: github.

Creating a GitHub account

Go to https://github.com/ and create an account.

Creating a branch on GitHub

Fork the oolite main branch.

Fetching your branch

We now repatriate the code locally: we fetch it.

On Linux

Installing git

We need git for this. Installing it depends on your distribution. For ubuntu: sudo apt-get install git

Fetching

$git fetch --help

Cloning the master branch (alternative to setting up your own branch)

The Oolite source is available from github. Use

git clone https://github.com/OoliteProject/oolite

to retrieve. Then

git submodule update --init

to fetch the various submodules.

Et voila! You've got the source ready to be compiled and/or tweaked.

Documentation

The documentation is automatically generated from the source code. When generated, it's 700mb heavy !

Pre-requisites

Installing Doxygen

On Linux

It depends on your distribution. For Ubuntu: sudo apt-get install doxygen

Generation

The documentation is generated into a html sub-directory.

On Linux

Go into your oolite directory and just do: $doxygen Doxyfile

Setting up your development environment

On Linux

Do as you wish :-)

I use vim + youcompleteme.

There's no IDE on linux managing objective-c (at least not Eclipse and Intellij). Auto-completion doesn't work in most of them because the xCode libraries aren't available (they're on OS X).

The only plugin for objective-c on eclipse is discontinued.

You can see the call hierarchy in the doxygen documentation.

Building

On Windows

Let's hear the wise words of another_commander (Updated 08th November 2013)

Seeing that, despite the quite comprehensive wiki instructions on how to make an Oolite executable, building from source on Windows is still a quite complicated matter, I have created a package that will hopefully simplify the process a lot and allow even the relatively inexperienced users to have a razor bleeding edge version of the game to play with and test. Please note that bleeding edge versions may cause spontaneous combustion of your computer, so you use them at own risk.

The download link to the Oolite Development Environment - Light Edition is this: https://drive.google.com/file/d/0BwG6R5Qjd1f2aWRxZDY5NkxlcG8/edit?usp=sharing The package contains the Objective-C compiler plus Posix environment (MinGW/MSYS), the Git package version 1.8.3 required for checking out and updating the source code and the required gnustep-base 1.20.1 files. No other downloads will be required.

Instructions on how to build an Oolite trunk executable from zero:

Download the environment and unzip it to a folder of your choice. IMPORTANT: The zip file you downloaded must be decompressed maintaining the folders' path structure, check your unzip program's documentation if you are not sure how to do this. Also note that in the unlikely case that your system is using drive letter O:, you will need to edit the files msys_x2/1.0/msys.bat and msys_x2/1.0/etc/fstab and change the references to o: to an unused drive letter. MORE IMPORTANT: Do not install this in a path containing spaces. We have had cases where the environment failed to work when installed in locations such as My Documents, Program Files etc.

Once unzipped, you must run the msys.bat file, found in <RootOfWhereTheEnvironmentWasInstalled>\msys_x2\1.0. You can create a shortcut to desktop for this file if you want. Once run, the environment will start up.

Important note: The latest development environment is by default configured for building the 64-bit version of the game, but it contains all files necessary for building the 32-bit flavor as well. To switch to the 32-bit version of the compiler, you need to navigate to the folder Msys_x2/1.0 and rename the following folders like this: 1) Devlibs -> Devlibs64 2) Mingw -> Mingw64 3) Devlibs32 -> Devlibs 4) Mingw32 -> Mingw. Reverse-rename to return to the 64-bit configuration. Never, ever mix 32-bit Devlibs with 64-bit Mingw or vice-versa. Expect build failure if you do so.

The rest of the steps are:

1. Create our working directory:

• mkdir /d/myoolite - to create a folder called myoolite under D:\. This is where we will check out the code.
• cd /d/myoolite - to enter our working directory.

2. Check out the oolite code:

• git clone https://github.com/OoliteProject/oolite.git - this will start copying the source code from the repository to your working dir. When finished, there will be a folder named oolite under the folder you performed the checkout. Next do a
• cd oolite to enter in the trunk folder, where the actual build will take place. Finally, execute this command to pull in all the binary dependencies needed for the full build (maybe you can take a coffee break here, this takes a while):
• git submodule update --init

3. Build the source:

• make debug=no - That's it! Go get a coffee while it builds, then come back and you will find two new folders under trunk: obj and oolite.app. obj contains the object files produced by the compiler and you don't need to worry too much about it. And of course you all know what oolite.app is.

4. Profit: Double click the oolite.exe file that resides in your D:\myoolite\trunk\oolite.app folder. You should see the splash screen followed by the familiar rotating Cobra. Now you can go and improve your Elite rating and give us some feedback from your testing while you're at it.

If at any later time you would like to update to the code that will be current by then, all you need to do is start up MSYS, then

• cd /d/myoolite/oolite
• git pull
• make debug=no

Good luck!