= macOS =

[[TracNav(TracNav/TOC_Development)]]

Here's how to get Orxonox up and running (compiling, currently you can't play the game) on macOS. It should build on anything from 10.8 (Mountain Lion) upwards (64-bit binaries for Intel processors only). The following procedure was tested on Mac OS X 10.12 (Sierra).

== Current Status (as of December 5, 2016) ==

It should compile with LLVM/Clang on the supported OS versions. Just follow the directions in the following sections. The problem is that you can't play the game right now due to loader errors.

Currently the dependencies are updated to use the right c++ standard library and are built for the x86-64 platform. The problem is that currently in the Lua library from CEGUI references it's symbols from the wrong library. This results in a run-time loader error at startup so you can't play the game right now. If you want to get it to run you have to compile the CEGUI dependencies yourself.

== Nice To Know ==

Porting Orxonox to Mac OS X has taken very long now and it wouldn't have been possible without the help of the community ([wiki:RetoGrieder 1337], [wiki:FabianLandau x3n], [wiki:DamianFrick Mozork] and many others). Although you can play Orxonox very well on the Mac, there is still a myriad of things that can and do go wrong - we'll be fixing those as we progress. One of the nicer new features is the addition of '''Cg shaders''' to Orxonox - maybe someone will manage to make a tutorial on that matter.

== Prerequisites ==

Lets assume you have a more recent installation of OS X (i.e. whatever we support: >= 10.8). To get you started, we first need to set up your development environment:
 * Xcode (version 4.4 or higher) it's free.
 * Cmake (You need at least 2.8.4. Get the prebuilt dmg-Image for Mac OS X [http://www.cmake.org/cmake/resources/software.html Cmake] or a command-line version with Homebrew)

== Source Files ==

Important Note: Currently, you CANNOT place your orxonox files on a path with white-spaces in it! Due to the fact that the entire Orxonox build structure  will not tolerate whitespaces, we will not try to implement it at all. Sorry - you'll just have to build Orxonox in folders without spaces. ;-)

Once you have your Xcode set up, you need to check out the source files and the dependency package. There are two possibilities to get the source files, either via Xcode or by using subversion in the terminal (/Applications/Utilities/Terminal). To get the files via subversion in the terminal follow these directions  [http://www.orxonox.net/wiki/SVN Subversion], or enter the following into your Terminal (without the dollar sign!):
{{{
$ mkdir -p ~/Development/Orxonox
$ cd ~/Development/Orxonox
$ svn co https://svn.orxonox.net/game/code/trunk
$ svn co https://svn.orxonox.net/game/data/trunk data_extern
$ mkdir trunk/build
}}}

Xcode automatically integrates with our svn repo. Do a "Checkout" of code/trunk and data/trunk. That's it, you can quit Xcode once the downloads are done.

== Dependencies ==

Orxonox has a pretty impressive list of dependencies and very few of them are pre-installed on our Macs. When building with cmake they are automatically downloaded. The following link is just for reference.

|| Dependency Package || Version || Size || Notes ||
|| [http://svn.orxonox.net/ogre/apple/precompiled_dependencies/OrxonoxDeps_110530_3.0_OSX.tar.bz2 "Mac OS X"] || 3.0 || 23M || Package for anything beyond kicklib2 ||

=== Building the dependencies on your own ===

For the suicidal ones, here's the dependency list, if you want to compile them yourself (files are preferentially dynamically linked):
Please note though: Apple uses an "install name" for its libraries. Follow the CocoaDev guide to set these install names appropriately: [http://www.cocoadev.com/index.pl?ApplicationLinking "Application Linking"]. You can find a little help at [http://www.orxonox.net/wiki/MacOSXDependencies "Dependencies for Mac OS X"].

|| Library name || Minimum Version || Recommended Version || Notes ||
|| [http://www.ogre3d.org/ "OGRE 3D Graphics Engine"] || 1.4 || 1.8.2 ||  ||
|| [http://www.cegui.org.uk/wiki/index.php/Main_Page "CEGUI (Crazy Eddie's GUI System)"] || 0.5 || 0.7.9 || We need: CEGUI.framework, CEGUILuaScriptModule.framework and ceguitolua++.framework. Plus, disable all ppc architectures ||
|| [http://www.boost.org/ "Boost libraries"]  || 1.35 || 1.49 || Hint: Use MacPorts ||
|| [http://www.lua.org/ "Lua (scripting language)"]         || 5.0 or 5.1 || 5.1.4 || Hint: Use the patchfile located in the Tools directory of the dependency package. ($patch -p1 -i patchfile) inside source dir. But preferentially use the Lua version shipped with CEGUI ||
|| Tcl (shell script language)      || 8.4 or 8.5 || - || Use Apple system version ||
|| OpenAL (audio)                   || (not yet specified) || - || Use Apple system version ||
|| ALUT (audio)                     || (not yet specified) || - || Can't be compiled on Apple. Use the package included in dependency package or consult [http://wiki.flightgear.org/index.php/FlightGear_Git_on_Mac_OS_X#Install_the_ALUT.framework "Flight Gear"]. Sadly, I do not know how they compiled this framework. ||
|| [http://www.xiph.org/vorbis/ "LibOgg"]                           || (not yet specified) || 1.2.1 ||  ||
|| [http://www.xiph.org/vorbis/ "LibVorbis"]                       || (not yet specified) || 1.3.2 ||  ||
|| [http://www.xiph.org/vorbis/ "LibVorbisFile"]                    || (not yet specified) || 1.3.2 || Comes with LibVorbis ||
|| ZLib (compression)               || (not yet specified) || - || Use Apple system version ||

LLVM/Clang (the default Xcode compiler) uses a different standard c++ library than gcc (libc++ instead of libstdc++, they are not binary compatible). So make sure that all dependencies are linking against libc++.

Apple Mac OS X uses the following library paths:
 * /usr
 * /usr/local
 * /opt/local (MacPorts source distribution: [http://www.macports.org/ MacPorts])
 * /sw (Fink binary distribution: [http://www.finkproject.org/ Fink])
 * /Library/Frameworks (for Apple frameworks; dynamically linked and self-contained structures. See [http://developer.apple.com/library/mac/#documentation/CoreFoundation/Conceptual/CFBundles/ CFBundles] for information.)
 * ~/Library/Frameworks
 * /System/Library/Frameworks
 * /Developer/Library/Frameworks

== Building Orxonox ==
Once you have everything in place, fire up Cmake. Choose your source and build directories and click "Configure" (if you followed the tutorial to the point its {{{~/Development/Orxonox/trunk}}} for the source directory and {{{~/Development/Orxonox/trunk/build}}} for the build directory). Choose either Xcode or Makefiles as build mode, whichever suits your preferences. Check the correct locations and then click "Configure", followed by "Generate". In case you're using Makefiles as build mode, you can just follow the normal steps to compile Orxonox: [http://www.orxonox.net/wiki/Buildsystem Buildsystem].
Otherwise switch to Xcode, open up the "Orxonox.xcodeproj" file inside your build directory and hit "Build". Let it simmer, while stirring the soup from time to time, and you're set to play the game (Hopefully). Mind always keeping an eye on the "Current Status" section, for I will write there if you have to follow special instructions.

== Playing Orxonox ==
I'll assume you have done the appropriate of the above sections. Run Orxonox by double-clicking on the Orxonox.app in the build directory.

== Debugging Orxonox ==
Apple includes its own crash reporter that collects the call stack and additional information upon the crashing of an application.