Porting Oolite
==============

Oolite is portable to any platform that supports SDL and GNUstep. It is
known to run on Linux, FreeBSD 5 and 6 and SGI IRIX. (The OS X version
is the 'canonical' version - Oolite appeared on Mac OS X first and was
later ported). It also runs under Windows.

Oolite doesn't care about the endian-ness of the architecture - so far,
it is known to have run on PowerPC, Intel/amd x86, amd x86_64 (and
presumably Intel's emt64 when it's available) and 64-bit MIPS.

Oolite uses the BSD strl* string functions. These aren't included in
GNU's libc, so make sure that src/BSDCompat files are included in your
build if you are using a libc that doesn't have the strl* functions.

Making binary packages for your platform
========================================
There is a tarball installer system. To generate a tarball installer
for your platform, run 'tools/mktarballs'. The result is deposited in
TarballPackages off the root of this repository.

There should be a directory 'deps/OPSYS-CPU-deps', where OPSYS is
the OS reported by 'uname' with no flags, and CPU is the result of
'uname -p' (for i686 etc. this is converted to x86). If you are making
a new dependency bundle for your platform, deps/OPSYS-CPU-deps should
contain the following:

In the root:

install     		A shell script that installs Oolite on the user's computer.
oolite.src			A shell script fragment that is used to make the shell
					script 'oolite' that runs the game.
oolite-update.src	A shell script fragment that can rsync updates.
OoliteReadMe.pdf	Brief players guide.
OoliteRS.pdf		Players Reference Sheet.
README.TXT  		Readme for your platform.

Subdirectories:
oolite-deps
      GNUstep  	A minimalist set of GNUstep run time files
      lib      Shared libraries that support the game

If your platform does not yet have this dependencies directory, you can
model yours on the Linux-deps directory. Most things will be the
same.

Issues you may encounter when building Oolite on a new platform
===============================================================

Symptom:
Altitude bar drawn right across the screen, time under the scanner
showing stupid value (it should be something like NNNNNNN:NN:NN:NN),
probably no rotating Cobra showing on startup (and no view out of the
window when you launch your ship)

Cause:
Bad maths.
floor(), part of the standard C math library, is returning funny values
or your int type is not at least 32 bits wide.
Make sure #include <math.h> is done in all applicable files; for Linux
this was put in oolite-linux.h which is included by every file.

Check that floor() returns a sensible value by writing a short program that
does:

int result;
double thing=180058016009.741669;
result=floor(thing / 86400.0);
printf("Result is %d and thing is %f\n", result, thing);

Result should equal 2084004. Try it including math.h and not including
math.h and note any differences. If it gives the right result with math.h
but the wrong result without, then you've not included math.h

In the case that your int type is only 16 bits, this will probably work:
#define int long

and put it in your equivalent of oolite-linux.h.

Additional info: see the manpage for floor().

TODO: Include an assertion on startup that causes the game to exit
immediately with an error message describing the problem if floor()
doesn't return the correct value. I'll only bother if this problem
keeps cropping up. An error message that can be reported is much
better than a vague description of these symptoms by some guy who
just wants to play the game.
--------------------------------------------------------------------------

Symptom: Floating point exceptions

Cause: Some rhs of / and % expressions are turning out to be zero (I
assume this isn't the case on OS X). In some instances, the simple
fix of doing an if(rhs_of_expression)... before the div or mod
operation is appropriate. It's probably best to look for the root
cause of why the rhs is zero in the first place to check that it's not
harmless and you're not going to hide a new problem or hide the root
cause by doing this test.

The location of the exception is easily found by doing 'make debug=yes'
and doing 'debugapp oolite.debug' and then looking at the line of code
it crashes in.