How To Compile

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

Prerequisite applications
Prerequisite libraries
Getting the source code
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.10 or later is required.
C++ compiler	Required	Visual Studio or MinGW	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.
vcpkg	Optional	https://vcpkg.io/en/getting-started	Not Tested	Not Tested	Highly recommended for Windows and necessary for the CMake presets.

Prerequisite libraries

Before compiling, the following development libraries need to be installed. Each Library will have its own instructions on how to install or use them. Some libraries are optional but come with caveats if not used.

If you are using vcpkg all of these libraries will be installed automatically when you run cmake later in the guide

Library	Minimum version	Windows	Linux	macOS	Notes
SDL	2.0	Required	Required	Required
Lua	5.1-5.3, 5.4.3+	Required	Required	Required	LuaJIT is no longer recommended. Lua 5.4.0 and 5.4.1 are not supported.
SDL_mixer	2.0	Optional	Optional	Optional^A	If not present, then there will be no audio.
FluidR3	N/A	Optional	N/A	N/A	SoundFont needed for MIDI playback on Windows if Audio is enabled (and custom SoundFont file not configured)
wxWidgets	2.8	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	N/A	Optional	N/A	If not present on Linux, then background MIDIs may not be played.
FFmpeg	4.x (version 7 is untested)	Optional	Optional	Optional	FFmpeg is required for movie support.
LibAV	N/A	N/A	N/A	N/A	LibAV is NOT SUPPORTED as of CorsixTH 0.66 (previous versions supported 11.1+). Use FFmpeg instead.
Doxygen	1.8	Optional	Optional	Optional	Only required for building documentation^B
LuaFileSystem	1.5	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	3	Optional	Optional	Optional	Used for version check and debugging. Can be obtained through luarocks
LuaSec	1	Optional	Optional	Optional	Used for version check and debugging. Can be obtained through luarocks

Note A - Homebrew's current recipe for sdl2_mixer does not include the ability to play most music formats. For full ability, including MP3 and FLAC, install instead with brew install --with-mpg123 --with-flac --with-libmikmod --with-fluid-synth https://raw.githubusercontent.com/Homebrew/homebrew-core/a9114e/Formula/sdl2_mixer.rb or manually.
Note B - Even if you do not intend to build the documentation you may have CMake warnings about the missing doxygen executable, which can be safely ignored.

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 https://github.com/CorsixTH/CorsixTH

If using a graphical Git client (for example, GitHub for Windows), then instruct it to fork https://github.com/CorsixTH/CorsixTH.

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 zip of the git repository is also available.

Compiling

Basic CorsixTH CMake Options

Option	Default	Description
BUILD_CORSIXTH	ON	Build the game itself
WITH_AUDIO	ON	Activate sound
WITH_MOVIES	ON	Activate in game movies
WITH_FREETYPE2	ON	Enhanced font support
BUILD_ANIMVIEW	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.
WITH_LUAJIT	OFF	Use LuaJIT instead of Lua
WITH_LUAROCKS	OFF	Include luarocks - Lpeg, LFS and optionally Luasocket and luasec - only on macOS

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

Compiling on Linux
Compiling on Windows
Compiling on macOS

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 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 (for versions before CorsixTH 0.66)

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 lua53 lua53-filesystem lua53-lpeg sdl2 sdl2_mixer timidity++ ffmpeg

This includes the FFmpeg movie library.

For Fedora:

sudo dnf install cmake freetype-devel git gcc gcc-c++ lua lua-filesystem lua-lpeg lua-socket lua-sec make SDL2 SDL2-devel SDL2_mixer SDL2_mixer-devel timidity++

In addition, if you would like in game movies, you will need FFMPEG from RPMFusion:

sudo dnf install ffmpeg ffmpeg-devel

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/liblua5.3.so ..
    # 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/liblua5.3.so ..

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!

Specific cmake for Raspberry Pi (tested on 4B)

cmake -DUSE_SOURCE_DATADIRS=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-Ofast -DNDEBUG -mcpu=cortex-a72" ..

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:

    make

and run:

    cd CorsixTH
    ./corsix-th

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

    make
    make install

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

    corsix-th

Compiling on Windows

The below provides a simple-to-use instruction set for compiling CorsixTH in Windows with Visual Studio 2022. You do not need to download any of prerequesites unless mentioned below.

Before starting you may wish to familiarise yourself with the Example Reference of directory structure for Windows instructions at the bottom of this section. Command line instructions can also be found there too.

Setup

Download Visual Studio's installer (C++ compiler in prerequisite applications)
- When installing:
  - Choose the workload from Desktop & Mobile > Desktop development with C++. This by default includes ability to operate localised vcpkg and cmake.
  - On the Optional section on Desktop development with C++ also select C++ MFC for latest vXXX build tools (x86 & x64)^[1]
  - On Individual Components search for "git" and choose Code tools > Git for Windows
Once installed, close the program for now.
Download the FluidR3 soundfont file (FluidR3 in prerequisite libraries) and keep it for later.
Create yourself a folder you want to work on this project in (e.g. C:\dev).
- You should make this in File Explorer to get the correct permissions easily.
- With vcpkg, using spaces or + in your directory structure is highly discouraged. Use - or _ instead.
Using git make a copy of the CorsixTH source files.

In Command Prompt or Powershell run: cd <path-to-your-project>.
Run git clone https://github.com/CorsixTH/CorsixTH.git. This creates a folder called CorsixTH (the repository)^[2].

Caution

When we open this project in Visual Studio it will automatically try to configure potentially under the incorrect preset. If you want to avoid that:

Open Visual Studio and use the "Continue without code" option so we can modify settings.
Go to Tools > Options > CMake > When cache is out of date: "Never run configure step automatically".
Note that doing this means you must use Project > Configure cache to run the configure process manaully.

CMake Configure

Open the project in Visual Studio:
- Go to File > Open > CMake. Navigate to your CorsixTH repository folder and select CMakeLists.txt.
  - The CMake has finished loading once "CMake Overview Pages" tab loads.
On the toolbar you will see a "Local machine" dropdown and another dropdown to the right of it potentially saying "linux-dev". On this second dropdown change this to "win-dev" (for development builds, recommended) or "win-x64-rel" (for release builds).
- If the preset is on "linux-dev" you may wish to stop the automatic Configure action. Click the chat bubble in the bottom left. Click the red stop button, then the following X to cancel configure.
Once you select the preset desired it will automatically begin configuring (unless you disabled automatic configure, see above).
- If this is your first run of configure for this preset it will take some time while it downloads and compiles all dependencies.
When CMake is completed a folder called build\<preset> will be made. This contains the build scripts. If you now open CorsixTH_Top_Level.sln you can make your build.

Compiling

On the toolbar you will see two dropdowns, the second potentially saying x64. On the first dropdown choose your build type (Release, Debug, or RelWithDebInfo).^[3]
On the Solution Explorer on the right hand side you will see an options called ALL_BUILD (for all modules) and CorsixTH (for just the program). Right click the option desired and select "Build". A CorsixTH\<build_type> folder will now be created in CorsixTH\<preset> containing the program.
- CorsixTH.exe may attempt to automatically launch from Visual Studio. You can close CorsixTH.exe safely.
- If you chose ALL_BUILD on win-dev an Animview\<build_type> also exists at the same hierarchy level. AnimView lets you view animations from the original Theme Hospital files.
Now prepare to complete the built artifact:
- You should now place the soundfont downloaded earlier as below:
  - For win-dev in the CorsixTH source CorsixTH\CorsixTH
  - For win-x64-rel and win-x86-rel in the CorsixTH\build\<preset>\CorsixTH\<build_type> folder.
- In win-dev preset, this program will launch as is without additional actions because it calls missing files from the CorsixTH source folder.^[4]
- In other presets, from the CorsixTH source, Lua files and other folders should be copied over. This includes:
  - CorsixTH.lua
  - Bitmap
  - Campaigns
  - Graphics
  - Levels
  - Lua

Footnotes
^{[1] The version number of this component can change over time. So use the newer version if presented. (at time of writing,
this was v143).

[2] If you are modifying C++ files for a test build, you would do those here.

[3] Due to an known issue in SDL2_mixer debug currently does not work. Use Release or RelWithDebInfo instead.

[4] win-dev builds can't be moved to other machines unless you change "USE_SOURCE_DATADIRS" in CMakePresets.json to OFF. You will then need to also add all other files mentioned in the artifact directory.}

Example Reference of directory structure for Windows instructions ([ ] denotes comments)

C:\dev
├─ CorsixTH [repository]
│  ├─ CMakePresents.json
│  ├─ CMakeLists.txt
│  ├─ build [cmake configure folder]
│  │  ├─ dev [named after cmake configure preset]
│  │  │  ├─ CorsixTH
│  │  │  │  ├─ Release [Built program named after build type]
│  │  │  ├─ AnimView [if built]
│  │  │  │  ├─ Release   
│  ├─ CorsixTH [source for Lua etc.]
│  │  ├─ CorsixTH.lua
│  │  ├─ Bitmap
│  │  ├─ Campaigns
│  │  ├─ Graphics
│  │  ├─ Levels
│  │  ├─ Lua

Basic instructions to compile fully via command line (without using Visual Studio IDE)

You can still compile using the command line, if you prefer and know how (and can manage prerequisites as necessary).
Note: You'll still need Visual Studio or the Build Tools for Visual Studio installed for this to work.

Basic example command line instructions (adjust according to your needs)

cmake --preset win-dev
cd build/dev
cmake --build . --config RelWithDebInfo

Some packaging notes in the Visual Studio instructions (Compling, step 3) may still be relevant depending on your build.

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 CorsixTH.app you cannot use Homebrew to generate your dependencies; they should be built with the same compile flags and targets as CorsixTH. Users who opt not to use Homebrew (or are redistributing) should see this page

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

    ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

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 --with-mpg123 --with-flac --with-libmikmod --with-fluid-synth https://raw.githubusercontent.com/Homebrew/homebrew-core/a9114e/Formula/sdl2_mixer.rb

For Lua version 5.1 rather than 5.4 use lua@5.1. Now to install the luarocks libraries. If there are multiple versions of Lua specified use the installation location in the following, i.e. for Lua 5.1 installed by homebrew,

    luarocks --lua-version=5.1 install lpeg
    luarocks --lua-version=5.1 install luafilesystem
    luarocks --lua-version=5.1 install luasocket
    luarocks --lua-version=5.1 install luasec OPENSSL_DIR=/usr/local/opt/openssl

Compiling CorsixTH (GUI)

CMake

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.

From the main window of CMake click Browse Source... and navigate to the directory that you cloned the Git repository to.
Now click Browse Build... and select a directory where you want the project to be generated, eg build.
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.
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
```
(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).
Now click Configure again to apply the changes.
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.
Click Configure again to apply the changes.
Now you should find you have no red lines in the main window. Click Generate to create the Xcode project.

Xcode

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:

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.
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.
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.
Finally run the install target to create a full app, or run the app with the run-corsix-th.sh file in the same folder.

Compiling CorsixTH (Terminal)

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

CMake

Open Terminal in the folder created by cloning the repository and create a makefile project. Run the following command, adjusting the CMake.app folder if necessary. CMake can be installed with brew install cmake.

/Applications/CMake.app/Contents/bin/cmake . -G"Unix Makefiles" -Bbuild -DCMAKE_INSTALL_PREFIX=/Applications -DWITH_LUAROCKS=on

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

make

Navigate to the Corsixth folder in the given build folder above, eg cd build.
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.
Build CorsixTH with make CorsixTH
Finally run the install target, with make install, to create a full app, or run the app with the run-corsix-th.sh file in the same folder.

Help!

If you're having difficulty please come to the Matrix room or Discord server. If you suspect there is an issue please create an issue on GitHub.

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.
If CorsixTH cannot play mp3 files even when compiled with Audio and SDL mixer you may not have the individual audio libraries (eg flac) or you have an old version of the mixer before the switch from smpeg to mpg123. This is fixed with a manual install without homebrew, or the following:

brew reinstall --with-mpg123 --with-flac --with-libmikmod --with-fluid-synth https://raw.githubusercontent.com/Homebrew/homebrew-core/a9114e/Formula/sdl2_mixer.rb

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

How To Compile

Prerequisite applications

Prerequisite libraries

Getting the source code

Compiling

Basic CorsixTH CMake Options

Compiling on Linux

Building the program (configuring)

Building the program (compiling)

Compiling on Windows

Compiling on macOS

Installing Required Libraries

Compiling CorsixTH (GUI)

CMake

Xcode

Compiling CorsixTH (Terminal)

CMake

make

Help!

Clone this wiki locally