• Prerequisite Applications
• Prerequisite Libraries
• Getting the source code
• Compiling
• Compiling on Linux
• Compiling on Windows
• Compiling on OS X
• LUA
• SDL
• SDL_Mixer
• CMake and XCode
• Compiling and
• wxWidgets
• Common errors
• CMake version check warning
• Exit with status 255 on OS X

Prerequisite Applications

In order to compile CorsixTH, the following applications need to be installed:

Prerequisite Libraries

Before compiling, the following development libraries need to be installed:

Getting the source code

The very latest source code can be checked out from the Subversion repository. With a command line Subversion client, the required command is:

svn checkout http://corsix-th.googlecode.com/svn/trunk/ corsix-th-read-only

If using a graphical Subversion client (for example, TortoiseSVN), then instruct it to checkout http://corsix-th.googlecode.com/svn/trunk/.

If you do not have a Subversion client, then the source code of the most recent release is available as a tarball from the downloads page, or a tarball of the subversion repository is also available.

Compiling

Compiling on Linux

The following commands may be suitable for installing the prerequisites; consult your distribution's package manager for full details, or alternatively, build the prerequisites from source.

For Ubuntu/Debian-based distributions:

sudo apt-get install build-essential
sudo apt-get install cmake
sudo apt-get install liblua5.1-0-dev
sudo apt-get install libsdl1.2-dev
sudo apt-get install libsdl-mixer1.2-dev
sudo apt-get install timidity

For Arch Linux:

sudo pacman -Sy base-devel cmake lua sdl sdl_mixer timidity++

Assuming that you have the prerequisites, and <checkout-path> is the top-level directory of CorsixTH source code (which should contain a file called CMakeLists.txt, and subdirectories called AnimView, CorsixTH, LFS, etc.), then the following commands should compile and run CorsixTH:

cd <checkout-path>
cmake .
cd CorsixTH
make
./CorsixTH

If you do not have SDL_Mixer installed, then use the following command for CMake instead of the above:

cmake -D WITH_AUDIO=OFF .

In a similar vein, if you want to use the OpenGL renderer rather than the SDL renderer, then add -D WITH_OPENGL=ON to the cmake command line.

Compiling on Windows

Note: This section assumes usage of Visual Studio 2008 or Visual C++ Express 2008. Other versions of Visual Studio will be similar, and other compilers will be similar for CMake part.

After obtaining the prerequisites and source code, run the CMake (cmake-gui) application. For both the source code and binary directories, browse to the top-level directory of the CorsixTH source code (which should contain a file called CMakeLists.txt, and subdirectories called AnimView, CorsixTH, LFS, etc.). Next, press the Configure button, and choose the version of Visual Studio which you have installed (if you want a 64 bit build of CorsixTH, then choose the 64 bit version here), and then press Finish. You will get an error message like the one below - this is normal, so do not be alarmed.

Note: The express editions of Visual Studio do not include 64 bit compilers, even on 64 bit platforms. Hence if using an express edition, do not choose the 64 bit version of Visual Studio in CMake (If using an express edition, you'll also need to trim the CorsixTH.rc file to avoid error RC1015).

In order to continue, CMake needs to be told where certain libraries are:

• LUA_INCLUDE_DIR - Browse to the src folder of the Lua 5.1 source code.
• LUA_LIBRARIES / LUA_LIBRARY - Browse to the lua5.1.lib or similar created by compiling Lua 5.1.
• SDLMAIN_LIBRARY - This can be left as SDLMAIN_LIBRARY-NOTFOUND.
• SDLMIXER_INCLUDE_DIR - If you have the SDL_Mixer library, browse to the top-level SDL_Mixer directory.
• SDLMIXER_LIBRARY - If you have the SDL_Mixer library, browse to the SDL_Mixer.lib file created by compiling SDL_Mixer.
• SDL_INCLUDE_DIR - Browse to the include directory of the SDL source code.
• SDL_LIBRARY_TEMP / SDL_LIBRARY - Browse to the SDL.lib file created by compiling SDL.
• WITH_AUDIO - If you do not have the SDL_Mixer library, then untick this box.
• WITH_DIRECTX - If you have the DirectX SDK, then tick this box and untick WITH_SDL.

Note that if the Lua settings do not appear, but you want to set them regardless, then changing the CMake dropdown from Simple View to Grouped View should reveal them.

Pressing Configure again should cause most of the red lines to become white, and the SDL_LIBRARY_TEMP line to become SDL_LIBRARY. Pressing Configure a second time should cause all lines to become white, and the Generate button to become enabled. Hence press the Generate button. If all went well, CMake should now be looking something similar to the following:

By pressing Generate, CMake will have produced a file called CorsixTH.sln within the CorsixTH subdirectory. Open this file with Visual Studio. Change the active configuration from Debug to Release in the normal way (the dropdown box on the toolbar), and then build the solution in the normal way (Build -> Build Solution (F7)).

This will create the file CorsixTH\Release\CorsixTH.exe. Note that if DLL versions of Lua, SDL, and/or SDL_mixer were used for compilation, then said DLLs will need to be copied to be alongside CorsixTH.exe.

Compiling on OS X

I'm going to focus on building a universal bundle here which will work on modern Intel Macs as well as the older PPC Macs. Lets do it from scratch. After you've downloaded the source, you need some tools:

LUA

You can obtain binaries of Lua from a number of different sources. From luabinaries, MacPorts, Fink and there's even a Lua framework available. However, most of these binaries were only compiled for Intel so I'm going to ignore them. That leaves us with two options, an easy option and a harder (but probably better) option.

The easiest option is to use the Lua framework mentioned above as, at time of writing, this uses a static library compiled for PPC as well as Intel. Simply download the "Framework only" option, extract the zip and place the Lua.framework folder in /Library/Frameworks.

The harder option is to compile Lua yourself from source. This is probably the better solution as it allows you to have direct control over which platforms to support etc. But you will have to make a few changes to the Lua Makefile. Below are the steps I used to compile and install a universal static lib of Lua:

1. Download and extract lua-5.1.4.tar.gz from the Lua website.

2. Open the lua-5.1.4/src/Makefile in your favourite text editor.

3. Find the line which looks like...

macosx:
	$(MAKE) all MYCFLAGS=-DLUA_USE_LINUX MYLIBS="-lreadline"

...and change it to look like...

macosx:
	$(MAKE) all MYCFLAGS="-DLUA_USE_MACOSX -isysroot /Developer/SDKs/MacOSX10.5.sdk -mmacosx-version-min=10.5 -arch ppc -arch i386 -arch x86_64" "MYLDFLAGS=-Wl,-syslibroot,/Developer/SDKs/MacOSX10.5.sdk -arch ppc -arch i386 -arch x86_64 -mmacosx-version-min=10.5"

...then save it.

This configuration will build a static lib compatible with PPC and Intel on MacOS 10.5 and above. You should ensure that whatever platforms and OS version you choose here are the same ones you select in CMake later on to ensure they're compatible.

4. Open a terminal and change into the lua-5.1.4 directory (e.g "cd /Users/Username/Downloads/lua-5.1.4").

5. Type "make macosx" and press return. This should perform the actual build process.

6. Type "sudo make install" and press return (enter your password when prompted). Lua should now be installed. You can test this by doing "lua -v" which should report the version of Lua as 5.1.4.

SDL

Download SDL from the official SDL website (at time of writing SDL-1.2.14.dmg is the latest) and copy the SDL.framework folder to /Library/Frameworks.

SDL_Mixer

If we want audio ingame, we must install SDL_mixer.

Download SDL Mixer from the SDL mixer project website (at time of writing SDL_mixer-1.2.11.dmg is the latest) and copy the SDL_mixer.framework folder to /Library/Frameworks.

CMake and XCode

After you've installed the libraries above, you now need CMake. Download and install it. Download the latest binary distribution from http://cmake.org/cmake/resources/software.html, install the app and open the application.

1. While you're in the main window of CMake, you should click Browse Source... and select the root of the CorsixTH source (containing folders such as AnimView, LDocGen, LFS, MapEdit etc.).

2. Click Browse Build... and choose where you want the project to be created.

3. Now, click Configure and let CMake create folders if necessary.

4. You should select XCode as generator for the project and Use default native compilers

5. You should now get some red fields. That is normal. If you scroll the log in the bottom, you should check that SDL, Lua and SDL_mixer are found:

Building CorsixTH
  SDL found
  Lua 5.1 found
  SDL_mixer found
Configuring done

6. Try clicking Configure once more and the fields should now be white again. The log should look like:

Note: Using SDL as renderer (default)
Note: SDL audio is enabled (default)

Building CorsixTH
  SDL found
  Lua 5.1 found
  SDL_mixer found
Configuring done

7. Before generating the XCode project we should set some Mac specific CMake settings.

7.1. Set CMAKE_OSX_ARCHITECTURES to "ppc i386 x86_64" (or whichever architectures you want to support).

7.2. Set CMAKE_OSX_SYSROOT to "/Developer/SDKs/MacOSX10.5.sdk" (or whichever OS you want to support).

7.3. Set CMAKE_INSTALL_PREFIX to "/Applications" (or wherever you want to place redistributable bundles).

7.4. (Optional) Enable WITH_OPENGL. This is optional but I like to enable this because it allows the zoom feature.

8. Click Configure again to apply the changes and then click Generate to build the XCode project.

If SDL, LUA or SDL_mixer are not found, try to look into the log, see where the error is and ask someone for help in the IRC channel or on the forum. They are really helpful!

9. Navigate to the folder you selected in step 2 and it should now contain an XCode project file named CorsixTH_Top_Level.xcodeproj. Double click on this file to open it in XCode.

10. Test if compilation works by clicking Build and Run. If this completes successfully then you are ready to start developing, if that's what you wish to do.

IMPORTANT: The build produced in step 10 isn't a redistributable build that will work on other machines. It does not copy across the frameworks that would be required to run the build on a machine that doesn't have them installed.

To produce a redistributable build, perform these extra steps:

11. Select MinSizeRel as the active configuration from the drop-down box in the top left of XCode. MinSizeRel is preferable to just a normal Release build as it is much more aggressive with regards to code stripping and produces a much smaller executable, particularly in the case of MapEdit and AnimViewer which use wxWidgets.

12. Expand Targets in the Groups & Files section of XCode, right click on install and click Build "install". This will place a redistributable bundle in the folder selected in step 7.3 above.

If you can't get this to work, let us know...

Compiling MapEdit and AnimViewer

To be compile these tools you will first need to build and install wxWidgets.

wxWidgets

Version 2.9.2 or above is required but, at the time of writing, this version is yet to be released (TODO Update). As a result, you will have to get the latest code from SVN and use that instead. A couple of changes need to be made before the build too. The instructions below take you through this.

1. Open up a terminal, change to the directory you want to place the wxWidgets source folder and run "svn checkout http://svn.wxwidgets.org/svn/wx/wxWidgets/trunk wxWidgets". This will place a folder called wxWidgets in your current directory with the latest source code.

2. Open wxWidgets/configure in your favourite text editor and find this bit of code:

# FIXME: To remove some day.
if test "x$host_alias" != x; then
  if test "x$build_alias" = x; then
    cross_compiling=maybe
    echo "$as_me: WARNING: If you wanted to set the --build type, don't use --host.
    If a cross compiler is detected then cross compile mode will be used." >&2
  elif test "x$build_alias" != "x$host_alias"; then
    cross_compiling=yes
  fi
fi

Directly after it put:

cross_compiling=yes

This will allow you to build a universal version of the libraries.

3. Open wxWidgets/setup.h.in in your favourite text editor and find this line:

#define wxDIALOG_UNIT_COMPATIBILITY   0

Directly after it put:

#define wxDEBUG_LEVEL 0

This will remove some debug features which stay present in a release build.

4. In the terminal window, ensure you are in the root of the wxWidgets directory and run the following command:

./configure --prefix=/usr/local --with-macosx-sdk=/Developer/SDKs/MacOSX10.5.sdk --with-macosx-version-min=10.5 --with-osx_cocoa --disable-shared --enable-universal-binary

5. Once the above has completed type "make" and press return. This will perform the build process and this can take quite a while.

6. Once building has finished type "sudo make install" and press return (enter your password when prompted).

wxWidgets should now be installed and you can build the map editor and anim viewer by following the "CMake and XCode" steps above, ensuring that BUILD_ANIMVIEWER and BUILD_MAPEDITOR are ticked. Note that, like the CorsixTH app, you will have to perform the extra steps to build redistributable versions of these tools.

Notes by others:

In terms of prerequisite libraries, Lua is fairly simple, whereas SDL is not quite so simple. For Lua, either use a system like MacPorts to install it, or make and compile an XCode dynamic library project (what is the exact term for a C (not Obj-C) dynamic library (not-framework) in XCode?) from all the files in the src directory of lua-5.1.4.tar.gz excluding lua.c, luac.c, and print.c.

For SDL, the easiest approach is to download and extract SDL-1.2.14.tar.gz. Then open a terminal/console/command-prompt window in the exacted directory, and enter the following three commands:

./configure
make
sudo make install

For SDL_Mixer, follow a similar process with SDL_mixer-1.2.11.tar.gz.

Common errors

CMake version check warning

If, when running CMake, you get (as part of the output) a warning like the one below:

CMake Warning (dev) in CMakeLists.txt:
  No cmake_minimum_required command is present.  A line of code such as
    cmake_minimum_required(VERSION 2.8)
   should be added at the top of the file.

Then you are pointing CMake at the wrong directory. Ensure that CMake is using the top-level CorsixTH directory containing a single file named CMakeLists.txt, not the lower-level CorsixTH directory containing CMakeLists.txt, config.txt, CorsixTH.lua, etc.

Exit with status 255 on OS X

If after compiling, XCode reports error/status 255 when you try to run CorsixTH, then most likely there was an issue with your configuration file. Launch CorsixTH from a terminal to see what it was.