Skip to content

How To Compile

Stephen E. Baker edited this page Sep 14, 2018 · 85 revisions

This page outlines how to compile the very latest version of CorsixTH. The following steps should be done

  1. Prerequisite applications

  2. Prerequisite libraries

  3. Getting the source code

  4. Compiling

Prerequisite applications

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

Application Status Windows Example Linux Example macOS Example Notes
CMake Required CMake Win32 installer CMake Unix/Linux source CMake OS X Universal Version 3.2 or later is required.
C++ compiler Required Visual Studio g++ Xcode The compiler must support C++ 11.
Git client Optional GitHub Desktop git GitHub Desktop Whilst technically optional, a git client is highly recommended.

Prerequisite libraries

Before compiling, the following development libraries need to be installed. For select platforms compiled prerequisite libraries can be obtained at The CorsixTH deps repository:

Library Minimum Version Windows Linux OS X Notes
SDL 2.0 Required Required Required
Lua 5.1 Required Required Required LuaJIT is no longer recommended.
SDL_mixer 2.0 Optional Optional OptionalA If not present, then there will be no audio.
wxWidgets 2.8 / 2.9.2 Optional Optional Optional Required to build the AnimView tool, but not the game itself.
FreeType2 2.5.3 Optional Optional Optional Required for font support beyond the original game's bitmap Latin fonts. Hence required for translations like Russian and Chinese.
Timidity Any Not required Optional Not required If not present on Linux, then background MIDIs may not be played.
FFmpeg 2.2.3 Optional Optional Optional FFmpeg is required for movie support. LibAV can also be used as an alternative.
LibAV 11.1 Optional Optional Optional LibAV is required for movie support. FFmpeg can also be used as an alternative.
Doxygen 1.8 Optional Optional Optional Only required for building documentationB
LuaFileSystem 1.5.0 Required Required Required Required at runtime. Can be obtained through luarocks
LPeg 0.9 Required Required Required Required at runtime. Can be obtained through luarocks
LuaSocket 2.0.2 (linux), masterC (Windows and OS X) Optional Optional Optional Used for version check and debugging
  • Note A - Homebrew installs SDL2_mixer without mpg123 by default. For mp3 ability install instead with brew install sdl2_mixer --with-mpg123.
  • Note B - Even if you do not intend to build documentation you may have CMake warnings about the missing doxygen executable, which can be safely ignored.
  • Note C - Luasocket 2.0.2 and 3.0-rc1 (the last two releases) do not work with Lua 5.2 or above on Windows and OS X. The fix is from Luasocket PR 69 and can be applied to 2.0.2 or 3.0-rc1 release with the following command, adjust for the luasocket installation path. curl -fLsS | patch -bfN --verbose /usr/local/share/lua/5.3/socket/http.lua Alternatively, it is in the master branch, confirmed to work with CorsixTH from 6d5e40c32 onwards.

Getting the source code

The latest source code can be cloned from the main Git repository. With a command line Git client, the required command is:

git clone

If using a graphical Git client (for example, GitHub for Windows), then instruct it to fork

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


Basic CorsixTH CMake Options

Option Default Description
WITH_AUDIO ON Activate sound
WITH_MOVIES ON Activate in game movies
WITH_FREETYPE2 ON Enhanced font support
WITH_LIBAV OFF Use LibAV instead of FFMpeg for movies
BUILD_ANIMVIEWER OFF Build the animation viewer as part of the build process.
USE_SOURCE_DATADIRS OFF Build the game to use Lua and other resources from the source directory instead of the install directory. This is highly recommended for developers, but should be off for packagers.

Compiling on the common operating systems is explained in more detail below:

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 cmake git liblua5.2-0 liblua5.2-dev libsdl2-dev libsdl2-mixer-dev timidity libfreetype6-dev lua-filesystem lua-lpeg doxygen liblua5.3-0 liblua5.3-0-dbg liblua5.3-dev

In addition, if you would like in game movies you can either use LibAV

sudo apt-get install libavcodec-dev libavformat-dev libavresample-dev libavutil-dev libavdevice-dev libswscale-dev libpostproc-dev libswresample-dev libavfilter-dev

or use the alternative movie library FFmpeg:

sudo apt-get install ffmpeg libavcodec-dev libavformat-dev libavresample-dev libavdevice-dev libavutil-dev libavfilter-dev libswscale-dev libpostproc-dev libswresample-dev

For Arch Linux:

sudo pacman -Sy base-devel cmake lua52 lua52-filesystem lua52-lpeg sdl2 sdl2_mixer timidity++ ffmpeg

This includes the FFmpeg movie library.

Building the program (configuring)

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 corsix-th:

    cd <checkout-path>
    mkdir build
    cd build
    cmake -DUSE_SOURCE_DATADIRS=ON ..  # <-- Note the dots at the end!

Note the -D_USE_SOURCE_DATADIRS=ON, this flag makes CorsixTH use the Lua and other binary resources from the source directory; which is useful for development. If you are building for distribution instead, or plan to install, then leave out that flag. CorsixTH will instead expect these resources to be in ${CMAKE_INSTALL_PREFIX}/share/corsix-th which is handled automatically by make install.

If you have multiple versions of lua installed, sometimes cmake gets confused about which one to use. You can fix this by being explicit:

    cmake -DUSE_SOURCE_DATADIRS=ON -DLUA_INCLUDE_DIR=/usr/include/lua5.3 -DLUA_LIBRARY=/usr/lib/i386-linux-gnu/ ..
    # Note that if you had already run CMake you should rm CMakeCache.txt first

For Debian9:

    cmake -DUSE_SOURCE_DATADIRS=ON -DLUA_INCLUDE_DIR=/usr/include/lua5.3 -DLUA_LIBRARY=/usr/lib/x86_64-linux-gnu/ ..

If you do not have SDL_Mixer or no FFMpeg installed, you can disable building by adding options to CMake like

    cmake -D WITH_AUDIO:BOOL=OFF -D WITH_MOVIES:BOOL=OFF ..  # <-- Note the dot at the end!

Building the program (compiling)

If running CMake did not give any error, and USE_SOURCE_DATADIRS was set then the program can be built with a simple:


and run:

    cd CorsixTH

If you opted not to use -DUSE_SOURCE_DATADIRS=ON then build with:

    make install

Assuming ${CMAKE_INSTALL_PREFIX}/bin is in your $PATH run with:


Compiling on Windows

Note: This section assumes usage of Visual Studio 2015 or 2017. The guide assumes you will be using the built in mechanism for downloading dependencies

Ensure you have the prerequisite applications installed and the option to add cmake.exe to your system path is selected during installation. A reboot may be required to correctly update the path variable if cmake.exe is not found.

Setting up

Navigate to the directory where you would like to build CorsixTH and create an empty folder inside called build. Clone CorsixTH using the following Git command:

git clone

The directory should now contain two subdirectories: build, and CorsixTH.

(Optional) CMake Compiler Selection

Cmake generates build files allowing compilers to find project dependencies. As it is a cross platform generator we can manually specify the compiler and architecture we will be building CorsixTH with using the generator name flag. The flags for supported compiler combinations on windows are listed below.

Compiler Architecture Generator Name
Visual Studio 2015 X86 Visual Studio 14 2015
Visual Studio 2015 X64 Visual Studio 14 2015 Win64
Visual Studio 2017 X86 Visual Studio 15 2017
Visual Studio 2017 X64 Visual Studio 15 2017 Win64


Open a command prompt (Note: bash will not work) and navigate into the empty build directory. Run the following command to which lets CMake select the best compiler to use for your system:

cmake.exe –DUSE_VCPKG_DEPS=ON ../CorsixTH

Alternatively the compiler can be specified by passing the generator flag from the above table like so:

cmake.exe –G “Your generator name” –DUSE_VCPKG_DEPS=ON ../CorsixTH

For example, if you wanted to compile an x64 binary using Visual Studio 2015 and the folder holding the source code was located at C:\corsixTH\src\ the command would be:

 cmake.exe -G "Visual Studio 14 2015 Win64" -DUSE_VCPKG_DEPS=ON C:/corsixTH/src


If this command ran successfully the build folder will now contain a folder called "CorsixTH_Top_Level.sln". Opening this file will load Visual Studio, change the build type to your choice such as Release then click Build Solution.

Visual Studio - Selecting build type

Build Solution Button

When the build completes a new folder called "CorsixTH" will be created in the build folder. Open this folder and the executable will be located within a folder with the same name as type of build you completed (e.g. Release/Debug...etc)

Bringing it all together

CorsixTH on Windows includes a .vcpkg.user file which will make CorsixTH use the Lua and other resource files from the source directory as long as you run CorsixTH from Visual Studio. If you do not intend to run CorsixTH from Visual Studio then you should either copy the Lua, and Bitmap directories and the CorsixTH.lua file to the directory where CorsixTH.exe is and run, or pass -DUSE_SOURCE_DATADIRS=ON to the cmake line above.

Compiling on macOS

Installing Required Libraries

For personal use most of the libraries can be installed using Homebrew and this is what we will be using to install them. Note: if you plan to redistribute the resulting you cannot use Homebrew to generate your dependencies; they should be built with the same compile flags and targets as CorsixTH.

Install Homebrew now by opening Terminal and using the following command:

    ruby -e "$(curl -fsSL"

If you receive any GUI popups, such as one to install xcode-select, proceed with these. Homebrew depends on Xcode Command Line Tools which includes git and many more useful programs. A list of the required libraries and the minimum versions required can be found at the top of this page.

Since we're using Homebrew it's a simple matter of running the following commands to install these libraries:

    brew install lua sdl2 freetype ffmpeg
    brew install sdl2_mixer --with-mpg123

For Lua version 5.1 rather than 5.3 use lua@5.1. Now to install the luarocks libraries. If there are multiple versions of Lua specified use a number in the following, i.e. luarocks-5.3.

    luarocks-5.3 install lpeg
    luarocks-5.3 install luafilesystem
    luarocks-5.3 install luasocket --from=

Compiling CorsixTH (GUI)


Now you need to open CMake which you installed earlier. Once you have done this follow the steps below to generate an Xcode project which we will use to compile CorsixTH.

  1. From the main window of CMake click Browse Source... and navigate to the directory that you cloned the Git repository to.

  2. Now click Browse Build... and select a directory where you want the project to be generated, eg build.

  3. Click Configure and allow CMake to create any directories if needed. When prompted select Xcode as the generator for the project and Use default native compilers.

  4. The main page will now show a large number of red lines, this is normal. Check the log at the bottom and you can see a number of red lines stating:

     Building CorsixTH
     SDL found
     Lua found
     SDL_mixer found
     FFmpeg found
     FreeType2 found
  5. (Optional) Now scroll to the CMAKE_INSTALL_PREFIX option. Set this to the directory where you want the compiled applications to be installed (e.g. /Applications).

  6. Now click Configure again to apply the changes.

  7. At this stage you may be presented with an error popup stating Error in the configuration process, project files may be invalid. This is perfectly normal and nothing to worry about. Simply click 'OK' to proceed.

  8. Click Configure again to apply the changes.

  9. Now you should find you have no red lines in the main window. Click Generate to create the Xcode project.


This stage is relatively straight forward. Navigate to the folder you selected in Step 2 above and open the CorsixTX_Top_Level.xcodeproj file. Now follow the steps below:

  1. In Xcode you will likely find you have an alert showing in the top bar. Click this, it will expand the drop down menu to the left. Click on Validate Project Settings. In the pop up window simply click Perform Changes. (If you are prompted to enable project snapshots, select Enable.) If you get a popup to install additional components allow these to install by selecting Install.

  2. In the menu bar select Product and then Build. The applications will now compile. During this process you will likely see many yellow alerts appear, these are nothing to worry about and the applications will still compile.

  3. Assuming everything went well you can now find the compiled applications in the directory you set in CMake step 5. If you did not set one it will be inside the Release or Debug folder.

  4. Finally run the install target to create a full app, or run the app with the file in the same folder.

Compiling CorsixTH (Terminal)

If you are comfortable with the command line this method may be quicker and preferable.


  1. Open Terminal in the folder created by cloning the repository and create a makefile project. Run the following command, adjusting the folder if necessary.
/Applications/ . -G"Unix Makefiles" -Bbuild -DCMAKE_INSTALL_PREFIX=/Applications

Note: If there are multiple versions of lua then specify which should be used by adding the following (for lua 5.1 installed by homebrew) -DLUA_LIBRARY=/usr/local/lib/liblua-5.1.dylib -DLUA_PROGRAM_PATH=/usr/local/bin/lua5.1 -DLUA_INCLUDE_DIR=/usr/local/lua5.1.


  1. Navigate to the Corsixth folder in the given build folder above, eg cd build.

  2. Check the options available to you with make help. If you used the Data Sources Dirs option in CMake then install will not be on this list.

  3. Build CorsixTH with make CorsixTH

  4. Finally run the install target to create a full app, or run the app with the file in the same folder.


If you're having difficulty please come to the IRC-(Chat) channel or post to the corsix-th-dev Google group. If you suspect there is an issue please create an issue on GitHub.

  1. If Xcode reports a missing <freetype/config/ftheader.h> file, your include path contains an older, conflicting version of the library. This is expected to be necessary if you have the Mono framework.

  2. If CorsixTH cannot play mp3 files even when compiled with Audio and SDL mixer you may have an old version of the mixer before the switch from smpeg to mpg123. This is fixed with the following:

brew uninstall --force --ignore-dependencies sdl2_mixer
brew install sdl2_mixer --with-mpg123
You can’t perform that action at this time.