Compile In Mac OS X

From FreeOrionWiki
Jump to: navigation, search


The instructions on this page have been made with the assumption in mind that you have at least some basic understanding of Xcode - what it is, how to use it (specifically, how to use it to compile C++ programs). We do not provide a "Getting started with Xcode" guide here. If you don't know anything about Xcode yet, we strongly encourage you to consult the Xcode documentation to make yourself familiar with it.

The same applies to the version control system the FreeOrion project uses for collaboration. As of March 29th, 2015, this is Git. You will need it to get the current sources, and keep them up to date.

Latest Version

This section is about compiling the latest version of FreeOrion on Intel Macs with Xcode 6 and OS X 10.10 (Yosemite) or later. Note: The instructions given here won't work with the old (now retired) FreeOrion SVN repository on SourceForge. Following the instructions will check out the latest version of the source code from the new Git repository on GitHub anyway, so you don't need to worry about that. However, if you want to work with very old versions of the source code (for whatever reason), you need to keep that in mind.

The application bundle that will get created when you follow these instructions should run on OS X 10.9 (Mavericks) or later. If that's not the case, please let us know.

Support for building FreeOrion with earlier versions of Xcode and OS X has been deprecated. You can find links to old wiki pages containing instructions for OSX 10.6/Xcode 3 and earlier at the bottom of this page. You'll need this specifically if you want to compile versions of the source code prior to revision 7120 in the old FreeOrion SVN repository.

Hardware Requirements

Intel Mac

CPU: Minimum: Core2 Duo; Recommended: Core i5 or better

RAM: Minimum: 4GB; Recommended: 8GB or more (the more the better...)

Software Requirements

Mac OS X 10.10 or later - Make sure all the latest updates and patches are installed.

Xcode 6.4 or later - Just get the latest version of Xcode from the Mac App Store for free.

Git - Git should be automatically installed when you install Xcode. If not, you can download Git for Mac here.

The latest version of the FreeOrion SDK - download from GitHub.

Build Directions

Step by step

  • Open the SDK .dmg file you've downloaded
  • Copy the contents of the .dmg file to an empty folder, which will be your working copy.
  • Run the bootstrap.command file
  • When FreeOrion has finished updating, close the terminal
  • Open the Xcode project located inside the 'Xcode' folder
  • The active scheme must be set to either 'Test Release', 'Release' or 'FreeOrion'. The first two schemes will create the FreeOrion application bundle and package it into a DMG image file. If you just want the application bundle and no DMG package, select the 'FreeOrion' scheme. Note: 'Test Release' builds the binaries with additional safety checks ("assertions") enabled, resulting in program abortions when these safety checks fail. So, if you aim for serious testing and uncovering of issues, use 'Test Release'. If you just want to happily play with a most up-to-date binary and not be bothered by program abortions because some minor internal safety checks fail, use 'Release'. 'FreeOrion' will create the same binaries as 'Test Release'.
  • Start the build process (press 'Command + B')
  • Depending on your system, this may take quite a while (on older systems probably more than 40 minutes). Note that the build process is very resource consuming, so your computer might turn unresponsive while building or even throw some strange build errors. In this case just restart the build process. Lather, rinse, repeat until building succeeds. However, this shouldn't take you more than three tries. If the errors persist, it's either because there is something wrong that's not caused by overtaxing your system (in which case please post a report on the forums), or your computer simply is not up to the task - in that case, sorry, there's nothing we can do about it.
  • The location of the FreeOrion application bundle depends on your Xcode settings (see Xcode documentation).
  • If the build fails, check out the troubleshooting section of this article, or post on the forums.

To keep your sources up-to-date you have to use the git pull command before building (Xcode should not run at that time).


  • Download and unpack the SDK
  • Run the bootstrap.command script
  • Build the project in Xcode


Can't find the app bundle / DMG file

Check the Xcode documentation to learn where Xcode places the products it creates during the build process. Quick solution: Go to Xcode preferences, 'Locations' tab, press the button labeled 'Advanced', select the 'Legacy' option. When you start the build process, this will create a new folder 'build' in the same directory the Xcode project is in. In case of a successful build the FreeOrion app bundle can be found in a folder with the name of the build configuration you've chosen ('Test' or 'Release') inside this 'build' folder.

Build process aborts after each error

Go to Xcode preferences, 'General' tab, check 'Continue building after errors'. This will cause the build process not to abort immediately after it encounters a build error.

Build process seems to choke system

You can try to disable the 'Parallelize Build' option in the 'Test Release', 'Release' and/or 'FreeOrion' schemes (whatever you decided to use). This option can be found in the 'Build' profile of the Edit Scheme dialog.

Other issues / errors / problems

Please post on the forums.

Old / obsolete Versions

Compiling with Xcode 3 on OS X 10.6

The old instructions for compiling with Xcode 3 on OS X 10.6 can be found here. If you want to build FreeOrion from source code versions prior to revision 7120 in the old FreeOrion SVN repository, you'll need to follow the instructions on that page.

Compiling on OS X 10.5 or earlier

Even older instructions for compiling FreeOrion with Xcode 2 on OS X 10.5 or earlier version can be found here. Note: These instructions have been copied from their original page almost without any adjustments, merely to keep them somewhere. If you're really crazy enough to try to build FreeOrion on OS X 10.5 or earlier, you might find something useful there. Be warned that we can't provide any help or support with that, so you're on your own.