Jump to content

Compiling (OpenApoc)

From UFOpaedia
Revision as of 21:14, 1 March 2026 by Deldonut1 (talk | contribs) (Major rewrite: updated to C++17/CMake 3.30; corrected dependency list; added macOS and troubleshooting sections)

This page describes how to compile OpenApoc from source on Windows, Linux, and macOS.

OpenApoc is written in C++17 and uses CMake (minimum version 3.30) as its build system. It targets GCC 8+, Clang 7+, and MSVC 2019+ (Visual Studio 2017 or later).

Important: You will need a copy of the original X-COM: Apocalypse CD image (cd.iso) placed in the data/ directory of the source tree. The build process extracts game data tables from this file.

Prerequisites

All platforms require:

  • Git — to clone the repository and fetch submodules
  • CMake 3.30 or newer
  • A C++17-capable compiler:
    • GCC 8+ (Linux)
    • Clang 7+ (Linux / macOS)
    • MSVC 2019+ / Visual Studio 2017 or later (Windows)
  • The original X-COM: Apocalypse disc image (cd.iso) — placed in data/

External Dependencies

The following libraries must be installed on your system (or via vcpkg on Windows). These are not bundled with the source code:

Library Purpose Notes
SDL2 Windowing, input, audio Required on all platforms
Boost (locale, program-options, uuid, crc) Localisation, settings management, hash functions Only these specific Boost libraries are needed
LibVorbis Ogg Vorbis music decoding Required on all platforms
Qt (Qt5 or Qt6 base) Launcher GUI Optional; can be disabled with BUILD_LAUNCHER=OFF
libunwind Debug backtracing Linux only; not needed on Windows or macOS

Note: Previous versions of this wiki page incorrectly listed tinyformat, libboost-filesystem-dev, libboost-system-dev, and qtdeclarative5-dev as dependencies. These are not required. The formatting library is fmtlib (bundled as a submodule), and only boost-locale and boost-program-options (plus boost-uuid and boost-crc) are needed from Boost.

Bundled Dependencies (Submodules)

The following libraries are included as Git submodules in the dependencies/ directory and are built automatically as part of the OpenApoc build. You do not need to install these separately:

Library Purpose
GLM Math library (vectors, matrices, etc.)
libsmacker Decoder for .smk video files
lodepng Reading/writing PNG image files
Lua Scripting language
miniz Zlib-compatible compression library
PhysFS (patched) Reading data from .iso files and directory trees
pugixml XML library for game data files
fmtlib (fmt) C++ string formatting library
magic_enum Header-only C++17 static reflection for enums

To fetch or update all submodules, run: 

git submodule update --init --recursive

Building on Windows

Requirements

  • Visual Studio 2017 or later, with the "Desktop Development with C++" workload installed
  • Vcpkg package manager (for external dependencies)

Step-by-step

  1. Install Visual Studio with the "Desktop Development with C++" workload.
  2. Install a Git client (e.g. GitHub Desktop) and clone the OpenApoc repository.
  3. Initialize the submodules:
    git submodule update --init --recursive
  4. Install Vcpkg and integrate it with Visual Studio.
  5. Install the required dependencies via vcpkg. For x64 builds:
    vcpkg --triplet x64-windows install sdl2 boost-locale boost-program-options boost-uuid boost-crc qt-base6-dev libvorbis
    For x86 builds, replace x64-windows with x86-windows.
    To see all supported architectures: vcpkg help triplet
  6. Copy your cd.iso file into the data/ directory.
  7. Open the OpenApoc directory in Visual Studio. If your version of Visual Studio does not have an "Open Folder" option, generate a project using CMake.
  8. Set the configuration to x64-Release (or x86-Release) — must match your vcpkg triplet. Release is recommended because Debug builds are very slow.
  9. Visual Studio should automatically detect and configure CMake. If you did not integrate vcpkg globally, set the CMake toolchain file manually:
    • Visual Studio 2017: Add to your CMake settings JSON:
      "CMAKE_TOOLCHAIN_FILE": "<path to vcpkg>\\scripts\\buildsystems\\vcpkg.cmake"
    • Visual Studio 2019+: Build → CMake Settings → Toolchain file → <path to vcpkg>\scripts\buildsystems\vcpkg.cmake
  10. Build the project. The first build may take a while, especially if vcpkg has not yet built all dependencies.

Running

When running from Visual Studio, the working directory is set to the project root, so the data/ folder is found automatically. If running outside Visual Studio, copy the entire data/ folder (including cd.iso) into the directory containing openapoc.exe.

Building on Linux

Ubuntu (22.04 / 24.04)

Install the required packages: 

sudo apt-get install libsdl2-dev cmake build-essential git libunwind8-dev \
    libboost-locale-dev libboost-program-options-dev qtbase5-dev libvorbis-dev

Clone the repository and initialize submodules: 

git clone https://github.com/OpenApoc/OpenApoc.git
cd OpenApoc
git submodule update --init --recursive

Copy the CD image: 

cp /path/to/cd.iso data/

Configure and build: 

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
make -j$(nproc)

Run: 

cd ..
./build/bin/OpenApoc

Fedora / Red Hat

Install the required packages (as root): 

yum groupinstall "Development Tools" "Development Libraries"
yum install git SDL2-devel cmake libunwind-devel qt6-qtbase-devel libvorbis-devel

Then follow the same clone, submodule, configure, and build steps as Ubuntu above.

Mageia

Install the required packages (as root): 

urpmi "cmake(sdl2)" libstdc++-static-devel boost-devel boost unwind-devel \
    task-c++-devel cmake git qt6-devel libvorbis-devel

Then follow the same clone, submodule, configure, and build steps as Ubuntu above.

Optional CMake flags (all distributions)

Flag Default Description
CMAKE_BUILD_TYPE (none) Set to RelWithDebInfo for optimized builds with debug symbols, or Release for maximum optimization
BUILD_LAUNCHER ON Build the Qt-based launcher GUI; set to OFF to skip Qt dependency
USE_SYSTEM_QT OFF Use system-installed Qt instead of the vcpkg package
ENABLE_TESTS ON Build unit tests (run with ctest from the build directory)
LTO OFF Enable link-time optimization
EXTRACT_DATA ON Run the data extractor as part of the default build target
CD_PATH data/cd.iso Path to the X-COM: Apocalypse disc image

Building on macOS

Tested on macOS Sequoia 15.6.

Requirements

Step-by-step

  1. Install Homebrew if not already present:
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  2. Clone the repository and initialize submodules:
    git clone https://github.com/OpenApoc/OpenApoc.git
    cd OpenApoc
    git submodule update --init --recursive
  3. Install dependencies via Homebrew:
    brew install cmake boost pkg-config sdl2 qt@6 libvorbis
  4. Add Qt to your PATH. If using zsh (default since macOS Catalina):
    echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.zprofile
    If using bash:
    echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.bashrc
    Then reload your shell or run source ~/.zprofile (or source ~/.bashrc).
  5. Copy the CD image:
    cp /path/to/cd.iso data/
  6. Configure and build:
    mkdir build
    cd build
    cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
    make -j$(sysctl -n hw.ncpu)
  7. Run the application:
    cd ..
    open ./build/bin/OpenApoc.app

Running Tests

After building, you can run the unit tests from the build directory: 

cd build
ctest

Common Issues / Troubleshooting

CMake version too old

OpenApoc requires CMake 3.30 or newer. If your distribution ships an older version, download the latest from cmake.org or install via pip install cmake.

Submodule errors / missing dependencies directory

If you see errors about missing files in dependencies/, ensure you have initialized the submodules: 

git submodule update --init --recursive

If you previously cloned without --recursive, this command will fetch all required submodules.

cd.iso not found

The build expects the original X-COM: Apocalypse disc image at data/cd.iso by default. You can change this path with: 

cmake -DCD_PATH=/path/to/cd.iso ..

Supported formats:

  • A standard .iso file (rename to cd.iso)
  • A directory containing extracted CD files (name the directory cd.iso)
  • GOG .cue/.bin files: rename the .cue file to cd.iso and place the .bin file alongside it in data/

Debug builds are very slow

This is expected. Use RelWithDebInfo for a build that is optimized but still has debug symbols: 

cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..

Missing Qt / launcher build fails

If you do not need the launcher GUI, disable it: 

cmake -DBUILD_LAUNCHER=OFF ..

Windows: Visual C++ Runtime errors

When running a pre-built binary on Windows, ensure you have the latest Visual C++ Redistributable installed.

OpenGL requirements

OpenApoc requires OpenGL 2.0 capable graphics hardware and drivers.

Linux: libunwind not found

On Ubuntu/Debian: 

sudo apt-get install libunwind8-dev

On Fedora/RHEL: 

sudo yum install libunwind-devel

macOS: Qt not found by CMake

Ensure Qt is on your PATH. After installing via Homebrew: 

export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"

Then re-run cmake.

See Also

Retrieved from "https://temp.ufopaedia.org/index.php?title=Compiling_(OpenApoc)&oldid=126335"