Developing Oolite

Overview

This page intends to allow you to setup an environment to develop Oolite.

Before you begin

If you do not know Objective C, see I want to help develop Oolite (2011).

Cloning or forking?

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. We used to use a svn repository, but this one isn't maintained anymore.

It is possible either to fork (create a copy of) 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.

Installing git

We need git for this.

On Linux

Installing git depends on your distribution. For ubuntu:

sudo apt-get install git

Getting the code by cloning the master branch

The Oolite source is available from github. First do

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

to retrieve. Then, in the directory this creates, do

 git submodule update --init

to pull in various other components such as dependencies, binary resources, and so on. The old SVN repository is no longer being updated.

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

Getting the code by forking your own branch (alternative to cloning the master branch)

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

git fetch --help

Documentation

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

This documentation is automatically generated on Github whenever the repository changes. The result is published as one of the build artifacts that you can download locally. The latest version is also published on https://ooliteproject.github.io/oolite/.

Pre-requisites

Installing Doxygen

On Linux

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

On Windows

You can download Doxygen binaries from the project's home page.

Generation

The documentation is generated into a html sub-directory.

On Linux & Windows

Just go into your oolite directory and do:

doxygen Doxyfile

Note that this will generate the Mac source documentation by default. For Linux and Windows, you will also have to pass the appropriate defines (e.g. OOLITE_WINDOWS, OOLITE_SDL etc.) to Doxygen.

If you don't want to install Doxygen and generate it yourself you can download the documentation from Github, or browse it directly on https://ooliteproject.github.io/oolite/.

Building

On AppleMac

At time of writing (Dec 2023), this is impossible with current versions. But see Running Oolite-Mac for what used to work.

On Windows

Current way to do it

Let's hear the wise words of another_commander (Updated 18th April 2023)

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/1u1IvBxiQjNvtrFs_2POaRP3IZhAi46N0/view?usp=sharing The package contains the Objective-C compiler plus Posix environment (MinGW/MSYS), the Git package version 2.16.2 required for checking out and updating the source code and the required gnustep-base 1.20.1 files. No other downloads will be required.

Alternatively, you can use the same Development Environment we deploy on github to produce the Windows nightly pre-release builds. This is guaranteed to always be the most recent and updated version, but it is a significantly bigger download. You can get it from https://github.com/OoliteProject/oolite-windows-build-env/releases/download/latest/DevelopmentEnvironment.zip

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, but instead of D: any available drive letter can be used. We will refer to D: here for simplicity.
• 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
• git submodule update
• make debug=no

Good luck!

Old Building Oolite from source

Updated on 09 January 2009 - (left here for reference, please use the instructions above).

Acknowledgments and thanks to Kaks‎ for providing them:

Important note: It is recommended that all packages for Windows be installed in paths that do not contain spaces. The same recommendation applies for the Windows username of the account the build is performed from. There have been reports of MSYS/make problems in such cases.

1. If you have an older version of GNUstep(GNUstep-base-1.11.1-gui-0.10.1-3 - from the wiki howto), uninstall it, then delete its root directory if it's still there(c:\GNUstep).
2. Google & download the following 2 packages, and - this is important - install them in this sequence: http://ftpmain.gnustep.org/pub/gnustep/binaries/windows/gnustep-system-0.19.2-setup.exe, http://ftpmain.gnustep.org/pub/gnustep/binaries/windows/gnustep-core-0.19.2-setup.exe
3. Google & download tortoiseSVN, install.
4. You now need the dependencies files for Windows. Download Local_20090108.zip [1].
5. Go to the Windows Start menu, navigate to and select Start>Programs>GNUstep>Shell
6. At the prompt :
   1. mkdir /Local
   2. mkdir /Local/oolite
   3. mkdir /Local/oolite/trunk . The first slash & the upper case L are very important!
7. From windows, extract the directories inside Local_20090108.zip to C:\GNUstep\Local
8. Still from windows go to C:\GNUstep\Local\oolite\trunk
9. It's empty. Right click>SVN checkout. The repository is svn://svn.berlios.de/oolite-linux/trunk . Wait for it to finish.
10. From inside the GNUstep shell
    1. export PATH=$PATH:/Local/bin
    2. cd /Local/oolite/trunk
    3. make debug=no
11. We're now ready to launch the compiled oolite! From inside the GNUstep shell:
    1. cd /Local/oolite/trunk
    2. openapp oolite.app

The instructions below are valid only for versions prior to 1.70, only use them as an alternative if the updated ones fail for whatever reason.

1. Download and install the necessary software
   1. Download and install svn for Windows: [2]. Accept all defaults given by the installer.
   2. Download and install GNUstep for windows: [3]. Accept all defaults given by the installer.
   3. Download the SDL files required to build Oolite: [4]
   4. Unzip this file to c:\GNUstep\Local
2. Get the source and build it (note, the source comes from the oolite-linux project)
   1. Start the GNUstep command line (Start -> Programs -> GNUstep Development -> MSYS for GNUstep) and issue the following commands:
   2. cd $GNUSTEP_LOCAL_ROOT
   3. export PATH=$PATH:$GNUSTEP_LOCAL_ROOT/bin
   4. mkdir oolite
   5. cd oolite
   6. svn checkout svn://svn.berlios.de/oolite-linux/trunk
   7. cd trunk
   8. make
3. To run the game in the build environment:
   1. Before running the first time: cp $GNUSTEP_LOCAL_ROOT/bin/*.dll oolite.app
   2. openapp oolite.app

Assuming you have installed one of Nic's releases as detailed above, you can easily keep updating the installation from the latest source. In the $GNUSTEP_LOCAL_ROOT/oolite/trunk directory, issue the commands:

1. export PATH=$PATH:$GNUSTEP_LOCAL_ROOT/bin
2. svn up
3. rm -rf oolite.app/Resources; make

You only need to issue the export PATH command when you first start the command line. The rm -rf command before make is required because GNUstep for Windows cannot parse the XML plist file format, and the build fails when it tries to read one of these generated each time the build is performed. This failure is not important, and the process still works, but it is annoying.

Then use the following script to copy the new files over the existing installation:

OA="/c/Program Files/Oolite/oolite.app"
cd $GNUSTEP_LOCAL_ROOT/oolite/trunk
if [ oolite.app/oolite.exe -nt "$OA/oolite.exe" ]; then
    echo "Updating oolite.exe"
    cp oolite.app/oolite.exe "$OA/oolite.exe"
fi

for a in AIs Config Images Models Music Sounds Textures; do
    for b in Resources/$a/*; do
        c=`basename $b`
        if [ $b -nt "$OA/Contents/Resources/$a/$c" ]; then
            echo "Updating with $b"
            cp $b "$OA/Contents/Resources/$a/$c"
        fi
    done
done

If you want to edit the source, Notepad++ has good Objective-C support and is free: [5]

Also see the Oolite-PC forum: [6]

Building Oolite-Linux

Dependencies

You will need the following components:

• The GNU Objective-C compiler (gcc-objc). Your distribution should have this available.
• GNUstep Startup. Your distro may provide the appropriate GNUstep development libraries.
• SDL development libraries including SDL_mixer and SDL_image. All Linux distros seem to have the main SDL library, but some do not seem to have SDL_image. This can be downloaded from the SDL Library Development website.
• OpenGL development libraries - your distribution will have these.
• To build Autopackages, you will also need the Autopackage development kit, which is available at Autopackage.org

The source code for these dependencies is also available at [7]

You may also want the following optional component:

• espeak, if you want speech (1.73 & later). Your distribution should have this; otherwise, see espeak.sourceforge.net.

Building

Once you have a source tree, you can build it by just typing 'make'. To run the newly-built code, then type 'openapp oolite'. If you want to build the Autopackage .package file, type 'makeinstaller'. This will leave a .package file in the build directory. You can then run this file to install the game.

Notes about the build process

• The makefile is called GNUmakefile rather than 'Makefile'; this seems to be the convention for GNUstep applications. If you are not using GNUmake, then you will probably need to 'make -f GNUmakefile'. However, it is recommended that you install gmake if you are using a platform (BSD) that doesn't include GNU make (it's a dependency for GNUstep anyway). The build process first builds all the Objective-C source (source code files end in '.m' which is the standard file extension for Objective-C) into the executable oolite.app/oolite and then copies the data into oolite.app/Contents.

• A new dependency on the SpiderMonkey JavaScript v1.70 library was introduced on SVN revision 1157. This requires some attention regarding the Linux build process. The full instructions on building the game successfully with JavaScript 1.70 on Debian can be found in the following forum post:
  https://bb.oolite.space/viewtopic.php?p=42188&highlight=#42188

• As of 1.73, a new 'Makefile' has been added to the project to simplify building Oolite. Assuming your system has all required build dependencies installed (as outlined above), you can build debug and optimised copies of Oolite with the following commands. The included Spidermonkey dependency is automatically built as well. For a full list of targets, use 'make -f Makefile help'.
  • make -f Makefile debug
  • make -f Makefile release

Notes about GNUstep

Several bugs have been found with gnustep-base1.19.3 which affect Oolite to a greater or lesser extent. As older versions of several popular Linux Distributions ship with this version of GNUstep, it is highly recommended that you compile and install a known good version of GNUstep for development. gnustep-base1.18 is known to be good. The current trunk (gnustep-base1.21.1) appears to also be ok.

This forum post details how to build and install gnustep for developing Oolite.

Objective-C

If you’re familiar with OO design concepts, learning Objective-C is about half a day’s work. If not, maybe a few days. Objective-C is a much, much smaller extension to C than C++ is. Take your choice of introductory documents:

• The Objective-C Programming Language – covers OO basics, just about the entire language (including bits not used in Oolite – the Exception Handling and Thread Synchronization chapter in particular) and the runtime library used in Apple’s implementation.
• Objective-C is Fun – covers most of the language in about three pages. (Assumes a knowledge of C.)
• Objective-C Beginner’s Guide – a more hands-on tutorial.

The biggest roadblock to most people seems to be the memory management model. (The chapter “Implementing Object Copy” can be considered an advanced topic in the context of Oolite, and the Core Foundation and Zones bit are of no interest.) The section Memory Management Rules is the really important bit.

That said, Oolite is not necessarily the best project to start with; taking a look at Apple’s or GNUstep’s tutorials. (The latter appears to be a rip-off– er, adaptation of the former.) These are geared towards GUI apps, though.

Ahruman, 2007 from Learning Objective-C

Links

• Building Spidermonkey (2020)

• Steam-ready (almost) (2022-24)