Kokua:Compiling (Mac)

Introduction
This guide describes how to compile the Kokua viewer for Mac OS X. If you have problems compiling Kokua, you can find help in the IRC channel or mailing list.

This guide assumes you have already acquired the Kokua source code.

Required Tools
You will need the following tools to compile Kokua for Mac:


 * An Intel Mac with Mac OS X 10.5 (Leopard) or later. PowerPC Macs and older versions of Mac OS X are not officially supported.
 * Xcode 3.0 or later. Your Mac should have come with an "Applications Install DVD", which has a copy of Xcode on it. Or, you can sign up for a free ADC membership, then download Xcode for free (although it is a very large file).
 * CMake 2.8.8 or later. We recommend (needs verification Nicky Perian) the "cmake-#.#.#-Darwin-universal.dmg" file (e.g. cmake-2.8.10-Darwin-universal.dmg).

Generating the Xcode Project
Once you have all the necessary tools, it's time to generate an Xcode "project file", which you will later open in Xcode to compile the viewer.

First, launch the CMake app. You should see an interface like this (click the image for a larger version):



For the "Where is the source code:" field, click the "Browse Source..." button, navigate to the the Kokua source folder, and choose the indra folder.

For the "'Where to build the binaries:" field, click the "Browse Build..." button, create a New Folder called kokua-build (preferably in the same parent folder as the Kokua source folder), then choose that folder. This is the folder where all the compiled files will be stored, such as the Xcode project file and the finished Kokua app.

Next, click on Configure. If this is the first time configuring, a window should appear that looks like this:



Select Xcode from the list, then press Done. The Configure window will disappear, returning you to the main CMake window. Some text will appear in the white box at the bottom, showing you the progress of the configuration process.

The configuration process may take several minutes the first time, while it automatically downloads additional libraries and artwork used by the viewer. When the process is complete, some text with a red background will appear in the area above the Configure button: AGL_LIBRARY, APPKIT_LIBRARY, etc. That is normal and expected, so don't worry. These are configuration settings, and the red background indicates that they are new. Most users do not need to change anything, but advanced users may wish to modify some of those settings by clicking on the value on the right side.

Next, click on Configure again. This time, you won't see a new window, and it will not take as long as the first time. When it's done, the red background in the configuration settings should become white/light blue, and the "Generate" button should become clickable.

Finally, click on Generate. This will generate the Xcode project file. The file will be called Kokua.xcodeproj, located in the kokua-build folder.

Compiling the Viewer
Once the Xcode project file (Kokua.xcodeproj) has been generated, it's time to finally compile the viewer! There are two ways to compile: in the Xcode application, or from the command line. We recommend that everyone compile in Xcode the first time, because it is easier to troubleshoot problems. After that, advanced users may wish to use the command line, since it uses system resources more efficiently.

Option 1: Compiling in Xcode
To compile in Xcode, you must of course launch Xcode. Xcode is not stored in the main Applications folder, but rather in /Developer/Applications. So, navigate to "Macintosh HD", then Developer, then Applications, and launch Xcode. Then, use the "File" menu > "Open...", navigate to your kokua-build folder, and open Kokua.xcodeproj. A window should appear that looks like this:



Most users should be able to compile with the default settings. But, advanced users may wish to configure the project:


 * You can switch Configurations with the drop-down menu in the top left. The default, "RelWithDebInfo", is a good balance between performance and debugging ability. "Debug" is slower than RelWithDebInfo, but more useful for debugging. "Release" is somewhat faster and has smaller file sizes than RelWithDebInfo, but is less useful for debugging.
 * You can modify many advanced settings by clicking on the top "Kokua" icon in the left sidebar, then pressing the blue "i" (Info) button (or using the &#8984;I keyboard shortcut), then selecting the "Build" section of the dialog that appears.

To begin compiling, you can either click on the hammer icon, or use "Build" menu > "Build" (or the &#8984;B keyboard shortcut). To watch the progress of the compile, use "Build" menu > "Build Results" (or the &#8679;&#8984;B keyboard shortcut).

The compile process uses a lot of system resources, so your computer will seem sluggish while compiling. It's best not to run any other processor-intensive applications while compiling (e.g. games, Photoshop, etc.). Compiling for the first time typically takes 30-90 minutes, depending on how powerful your computer is. After the first time compiling, recompiling usually takes less than 10 minutes.

With luck, the viewer will successfully compile, with no errors. You can then launch Kokua by pressing the green circle with triangle (Go) button, or using "Run" menu > "Go". Or, you can find the compiled Kokua app in the kokua-build/newview/RelWithDebInfo folder. (If you selected a different Configuration, the folder name will be "Debug" or "Release" instead of "RelWithDebInfo".)

If you encounter errors or have problems compiling Kokua, you can find help in the IRC channel or mailing list.

Option 2: Compiling from the Command Line
For advanced users, it's also possible to compile Kokua from the command line with the xcodebuild command. This way is more efficient (i.e. quicker to compile), because of the reduced overhead by not running Xcode. But, it's much harder to identify problems when they occur, so we don't recommend doing it this way until you have successfully compiled using Xcode at least once.

First, open a terminal window. Navigate to Applications, then Utilities, and launch the Terminal application. Then, enter these commands (assuming your kokua-build folder is in your home folder):

cd ~/kokua-build xcodebuild --configuration RelWithDebInfo

You may wish to use "Debug" or "Release" instead of "RelWithDebInfo", to select those configurations instead (discussed above).

As the viewer compiles, a lot of text will scroll by in the terminal window. If it compiles successfully, you can find the compiled Kokua app in the kokua-build/newview/RelWithDebInfo folder. If you selected a different configuration, the folder name will be "Debug" or "Release" instead of "RelWithDebInfo".

If you encounter errors or have problems compiling Kokua, you can find help in the IRC channel or mailing list.