Difference between revisions of "Mac Development Guide"

From FreeSpace Wiki
Jump to: navigation, search
m (Getting Apple Xcode: Dammit...)
m (Reflect source code hosting via Git)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This page provides background and instructions to setup the Apple Xcode development environment in order to compile FreeSpace 2 Open SCP. After following these instructions you will have a working Xcode build environment, a checked out copy of the latest FS2_Open source code, and compiled binaries of the latest revision of the FS2_Open engine.
+
This page provides background and instructions to setup the Xcode development environment in order to compile FreeSpace 2 Open SCP. After following these instructions you will have a working Xcode build environment, a checked out copy of the latest FS2_Open source code, and compiled binaries of the latest revision of the FS2_Open engine.
  
 
[[Image:Xcode icon.png‎|right|110px]]
 
[[Image:Xcode icon.png‎|right|110px]]
  
==Getting Apple Xcode==
+
==Getting Xcode==
Xcode is the integrated development environment (IDE) that Apple provides free of charge for the Mac OS platform. It is the Mac equivalent to Microsoft Visual Studio. In practice, Xcode provides a graphical interface to an underlying GCC or LLVM compiler; with the addition of platform libraries (Frameworks), code completion, project management and the other features you would expect of a modern IDE.
+
Xcode is the integrated development environment (IDE) that Apple provides free of charge for the Mac OS platform. It is the Mac equivalent to Microsoft Visual Studio. In practice, Xcode provides a graphical interface to an underlying Clang/LLVM compiler; with the addition of platform libraries (Frameworks), code completion, project management and the other features you would expect of a modern IDE.
  
Xcode is free (once again as of version 4.1), and comes on a second disk provided alongside your operating installation disks with your Mac. However, the latest version of Xcode is available free from the Mac App Store (you do not have the enrol in the $99/year Mac Developer Program to access this download).
+
The latest Xcode is available free from the Mac App Store.  Xcode 3.2.6 is available to those with a free Apple Developer account on the [https://developer.apple.com/downloads/index.action Apple Developer Downloads] page, search for 'Xcode 3.2.6' and it should be the only result.  This may be useful for those with older hardware/software needs.
  
It is '''strongly recommended''' that you downloaded the latest version of Xcode compatible with your Mac OS version, as prior versions have bugs which prevent FS2_Open from compiling properly.
+
It is '''strongly recommended''' that you update to the latest version of Xcode compatible with your Mac OS version, as prior versions have bugs which prevent FS2_Open from compiling properly.
  
 
{| style="text-align:center"
 
{| style="text-align:center"
 
|+ ''Known working combinations''
 
|+ ''Known working combinations''
! !! Mac OS X 10.7 !! Mac OS X 10.6.8 !! Mac OS X 10.5.8 !! Mac OS X 10.4.11
+
! !! OS X 10.9 !! OS X 10.8 !! OS X 10.7
 +
|-
 +
! Xcode 5.1.1
 +
| <font color=green>Yes</font> || <font color=green>Yes</font> || n/a
 +
|-
 +
! Xcode 5.0.2
 +
| <font color=green>Yes</font> || <font color=green>Yes</font> || n/a
 
|-
 
|-
 
! Xcode 4.2.1
 
! Xcode 4.2.1
| <font color=orange>Partially</font> || <font color=red>Not as yet</font> || n/a || n/a
+
| n/a || n/a || <font color=orange>Partially</font>  
 
|-
 
|-
 
! Xcode 3.2.6
 
! Xcode 3.2.6
| <font color=green>Yes</font> || <font color=green>Yes</font> || n/a || n/a
+
| n/a || <font color=green>Yes</font> || <font color=green>Yes</font>
|-
 
! Xcode 3.1.4
 
| n/a || <font color=red>No</font> || Unknown || Unknown
 
|-
 
! Xcode 3.0.0
 
| n/a || Unknown || <font color=green>Yes</font> || Unknown
 
|-
 
! Xcode 2.5
 
| n/a || Unknown || Unknown || Unknown
 
 
|}
 
|}
  
 +
==Getting FreeSpace 2 Open SCP source code==
 +
 +
Open Terminal.app through Spotlight, or it can be found in /Applications/Utilities/Terminal.app. This is the console command line for Mac OS. You will need a location to save the checked out source code. The following commands will create a new folder in your personal Documents called 'coding' and then within a subfolder specific for FS2_Open called 'fs2_open' checkout the latest source code.
 +
 +
$ cd Documents
 +
$ mkdir coding
 +
$ cd coding
 +
$ git clone https://github.com/scp-fs2open/fs2open.github.com.git fs2open
  
'''Steps'''
 
  
* Access [http://developer.apple.com/technologies/xcode.html the latest Xcode release]. You can just select the Mac Dev Center as the iPhone specific SDK is not required.
+
Open Finder and browse to ~/Documents/coding/fs2open to see the new files that have been downloaded from the FS2_Open source code repository.
* If you are not already, register as an Apple Developer (free).
 
* Download the Xcode DMG to your computer, and open it.
 
  
==Installing Apple Xcode==
+
FS2_Open currently uses some precompiled third party Frameworks to handle music and video on Mac OS, which are stored in compressed form within the source code repository. Open the 'projects' folder and then 'Xcode4'. This is the location of recent Xcode specific project files and settings. For now, double click on Frameworks.tgz to uncompress these Frameworks to a new folder called Frameworks.
It is now time to install the Xcode IDE and the accompanying Frameworks and tools.
 
  
[[Image:Xcode-chose-package-300x212.png‎|right|thumb]]
+
Your local checkout of the source code can be keep up to date with the latest changes by opening Terminal.app again, and running the following commands
[[Image:Xcode-install-successful-300x212.png‎|right|thumb]]
 
'''Steps'''
 
  
* Open the Xcode DMG or inserted DVD by double clicking on the icon.
+
$ cd Documents/coding/fs2open
* As you run through the installation you will eventually be greeted with the options to install different parts of Xcode.
+
$ git pull
** The essential package is always needed, however system tools, UNIX support, documentation and Mac OS X 10.4 support is optional.
+
 
** I recommend you install the documentation and system tools, both of these are quite useful especially the system tools option.
+
Xcode and the FreeSpace 2 Open SCP source code is now setup, so let's start our first compilation by double clicking on the FS2_Open.xcodeproj Xcode project file.
** The UNIX dev support is only need if you want to play around with some high level stuff.
 
** For more information read the little description box. If you ever find your need some of the products in the list you can always insert your DVD/DMG again and reinstall the missing apps.
 
* Once the installation is complete you can unmount the DMG or eject the DVD.
 
  
  
Xcode will now be available in Spotlight. If you followed the default settings, Xcode.app was installed at /Developer/Applications/Xcode.app. It may be useful to open Xcode.app, then right click on the icon in the Dock, go to 'Options' and set 'Keep in Dock'
+
==Compiling FreeSpace 2 Open SCP source code (GUI)==
  
You can open Xcode and take a look around if you'd like now. It will pop up with the new project wizard, and appear pretty spartan at the moment, so let's get the FreeSpace 2 Open SCP source code and the prepared Xcode project file for FS2_Open so that the engine can be compiled.
+
Click the 'Build' button or press Apple key+B. This should complete successfully, and once done the binary application can be found within 'projects/Xcode4/build/'. Open the folder with the same name as the build type you selected previously to find the compiled FS2_Open application.
 +
[[Category:Source Code Project]][[Category:FreeSpace_Open_on_Mac]]
  
  
==Getting the FreeSpace 2 Open SCP source code==
+
==Compiling FreeSpace 2 Open SCP source code (Command line)==
  
Open Terminal.app through Spotlight, or it can be found in /Applications/Utilities/Terminal.app. This is the console command line for Mac OS. You will need a location to save the checked out source code. The following commands will create a new folder in your personal Documents called 'coding' and then within a subfolder specific for FS2_Open called 'fs2_open' checkout the latest Subversion revision.
+
Open Terminal.app and run the following commands to build a Debug version of FS2_Open
  
  cd Documents
+
  cd Documents/coding/fs2_open/projects/Xcode4
mkdir coding
+
xcodebuild
cd coding
 
svn checkout svn://svn.icculus.org/fs2open/trunk/fs2_open fs2_open
 
  
 +
In order to build an AddressSanitizer build, first a trunk version of Clang/LLVM must be downloaded and installed as the Apple-supplied Clang does not enable AddressSanitizer features.
  
Open Finder and browse to ~/Documents/coding/fs2_open/ to see the new files that have been downloaded from the FS2_Open Subversion source code repository.
+
Following the instructions at http://clang.llvm.org/get_started.html
  
FS2_Open currently uses some precompiled third party Frameworks to handle music and video on Mac OS, which are stored in compressed form within Subversion. Open the 'projects' folder and then 'Xcode'. This is the location of all Apple Xcode specific project files and settings. For now, double click on Frameworks.tgz to uncompress these Frameworks to a new folder called Frameworks.
+
Then use this trunk build of Clang instead of the Apple-supplied Clang to build FS2_Open with AddressSanitizer
  
Your local SVN checkout of the FreeSpace 2 Open SCP code can be keep up to date with the latest changes by opening Terminal.app again, and running the following commands
+
cd Documents/coding/fs2_open/projects/Xcode4
 +
export CC=/path/to/llvm/../build/Debug+Asserts/bin/clang
 +
export CXX=/path/to/llvm/../build/Debug+Asserts/bin/clang++
 +
export CFLAGS=-fsanitize=address
 +
export LDFLAGS=-fsanitize=address
 +
xcodebuild CC=$CC CXX=$CXX OTHER_CFLAGS=$CFLAGS LDFLAGS=$LDFLAGS LDPLUSPLUS=$CXX CLANG_LINK_OBJC_RUNTIME=NO
  
cd Documents/coding/fs2_open
+
You may need to open the Xcode GUI and copy the following file into the Linked Frameworks
svn up
 
  
Xcode and the FreeSpace 2 Open SCP source code is now setup, so let's start our first compilation by double clicking on the FS2_Open.xcodeproj Xcode project file.
+
/path/to/llvm/build/Debug+Asserts/lib/clang/3.5.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib
  
==Compiling the FreeSpace 2 Open SCP source code==
+
FS2_Open must be run from the Terminal to enable to AddressSanitizer feature at runtime. Additionally, to ensure line references and the like are cleanly shown the output must be piped to a Python script which symobilizes line references
{{note|The exact process is dependent on the version of Xcode, but the general approach is the same}}
 
[[Image:Xcode-fs2open.png‎|right|thumb|400px|''Xcode 3.2.2 as it appears after opening the FS2_Open Xcode project file'']]
 
To compile a FS2_Open build without making any changes is straightforward. In the top left of Xcode 3.2.2 you will see a dropdown box with text similar to "10.4 | [Build Type] | FS2_Open | ppc". You can select the type of build with the [Build Type] section.
 
  
Once picked, click the 'Build' button. For the first time, this will take some time (dependent upon the speed of your hardware). This should complete successfully, and once done the binary application can be found within 'projects/Xcode/build/'. Open the folder with the same name as the build type you selected previously to find the compiled FS2_Open application.
+
./FS2_Open\ \(debug\).app/Contents/MacOS/FS2_Open\ \(debug\) 2>&1 | /path/to/llvm/projects/compiler-rt/lib/asan/scripts/asan_symbolize.py | c++filt
[[Category:Source Code Project]][[Category:FreeSpace_Open_on_Mac]]
 

Latest revision as of 04:22, 3 May 2015

This page provides background and instructions to setup the Xcode development environment in order to compile FreeSpace 2 Open SCP. After following these instructions you will have a working Xcode build environment, a checked out copy of the latest FS2_Open source code, and compiled binaries of the latest revision of the FS2_Open engine.

Xcode icon.png

Getting Xcode

Xcode is the integrated development environment (IDE) that Apple provides free of charge for the Mac OS platform. It is the Mac equivalent to Microsoft Visual Studio. In practice, Xcode provides a graphical interface to an underlying Clang/LLVM compiler; with the addition of platform libraries (Frameworks), code completion, project management and the other features you would expect of a modern IDE.

The latest Xcode is available free from the Mac App Store. Xcode 3.2.6 is available to those with a free Apple Developer account on the Apple Developer Downloads page, search for 'Xcode 3.2.6' and it should be the only result. This may be useful for those with older hardware/software needs.

It is strongly recommended that you update to the latest version of Xcode compatible with your Mac OS version, as prior versions have bugs which prevent FS2_Open from compiling properly.

Known working combinations
OS X 10.9 OS X 10.8 OS X 10.7
Xcode 5.1.1 Yes Yes n/a
Xcode 5.0.2 Yes Yes n/a
Xcode 4.2.1 n/a n/a Partially
Xcode 3.2.6 n/a Yes Yes

Getting FreeSpace 2 Open SCP source code

Open Terminal.app through Spotlight, or it can be found in /Applications/Utilities/Terminal.app. This is the console command line for Mac OS. You will need a location to save the checked out source code. The following commands will create a new folder in your personal Documents called 'coding' and then within a subfolder specific for FS2_Open called 'fs2_open' checkout the latest source code.

$ cd Documents
$ mkdir coding
$ cd coding
$ git clone https://github.com/scp-fs2open/fs2open.github.com.git fs2open


Open Finder and browse to ~/Documents/coding/fs2open to see the new files that have been downloaded from the FS2_Open source code repository.

FS2_Open currently uses some precompiled third party Frameworks to handle music and video on Mac OS, which are stored in compressed form within the source code repository. Open the 'projects' folder and then 'Xcode4'. This is the location of recent Xcode specific project files and settings. For now, double click on Frameworks.tgz to uncompress these Frameworks to a new folder called Frameworks.

Your local checkout of the source code can be keep up to date with the latest changes by opening Terminal.app again, and running the following commands

$ cd Documents/coding/fs2open
$ git pull

Xcode and the FreeSpace 2 Open SCP source code is now setup, so let's start our first compilation by double clicking on the FS2_Open.xcodeproj Xcode project file.


Compiling FreeSpace 2 Open SCP source code (GUI)

Click the 'Build' button or press Apple key+B. This should complete successfully, and once done the binary application can be found within 'projects/Xcode4/build/'. Open the folder with the same name as the build type you selected previously to find the compiled FS2_Open application.


Compiling FreeSpace 2 Open SCP source code (Command line)

Open Terminal.app and run the following commands to build a Debug version of FS2_Open

cd Documents/coding/fs2_open/projects/Xcode4
xcodebuild

In order to build an AddressSanitizer build, first a trunk version of Clang/LLVM must be downloaded and installed as the Apple-supplied Clang does not enable AddressSanitizer features.

Following the instructions at http://clang.llvm.org/get_started.html

Then use this trunk build of Clang instead of the Apple-supplied Clang to build FS2_Open with AddressSanitizer

cd Documents/coding/fs2_open/projects/Xcode4
export CC=/path/to/llvm/../build/Debug+Asserts/bin/clang
export CXX=/path/to/llvm/../build/Debug+Asserts/bin/clang++
export CFLAGS=-fsanitize=address
export LDFLAGS=-fsanitize=address
xcodebuild CC=$CC CXX=$CXX OTHER_CFLAGS=$CFLAGS LDFLAGS=$LDFLAGS LDPLUSPLUS=$CXX CLANG_LINK_OBJC_RUNTIME=NO

You may need to open the Xcode GUI and copy the following file into the Linked Frameworks

/path/to/llvm/build/Debug+Asserts/lib/clang/3.5.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib

FS2_Open must be run from the Terminal to enable to AddressSanitizer feature at runtime. Additionally, to ensure line references and the like are cleanly shown the output must be piped to a Python script which symobilizes line references

./FS2_Open\ \(debug\).app/Contents/MacOS/FS2_Open\ \(debug\) 2>&1 | /path/to/llvm/projects/compiler-rt/lib/asan/scripts/asan_symbolize.py | c++filt