Skip to content

Build

Jump to bottom Edit New page
Garrett Guillotte edited this page Jan 8, 2026 · 29 revisions

EmptyEpsilon is an open-source project, which allows you to build the game yourself from its source code. If official builds aren't available for your operating system or architecture, you can likely build it yourself and create a distributable package to install it on other similar systems. You can also customize EmptyEpsilon beyond its Modding support and GUI theming by modifying its code and building your own version.

Table of contents

Prerequisites

You must have:

  • A C++ compiler and development toolchain for your operating system.
  • CMake, an automation tool for building software.
  • Either Make or Ninja, both software build systems. Ninja is recommended and used in most of this wiki's documentation.
  • SDL2 development libraries.

The steps to install these tools depend on your operating system. See the Build subpages for your operating system for details.

Building on macOS and non-Android ARM processor architectures is possible, but isn't officially supported by daid. The EmptyEpsilon community might be able to help you with build issues, but issues specific to macOS or ARM builds might not be resolved.

Download the code repositories

EmptyEpsilon, and the SeriousProton engine that it runs on, are separate projects hosted on GitHub. To build them from source, you must acquire the source code.

The easiest way to acquire the source for a specific version of EmptyEpsilon and SeriousProton is to download it from each repository's releases pages:

However, a more convenient way to stay up-to-date with bleeding-edge code changes, and the best way to make your own changes to the codebase, is to install and use Git.

Once you've installed Git, you can clone the repository to download the latest version:

git https://github.com/daid/EmptyEpsilon
git https://github.com/daid/SeriousProton

By default, this clones the entire repository and uses the master branch, which is the latest development code. To build a specific version of EmptyEpsilon for compatibility with official releases, see Check out a specific version tag.

The two repositories should ideally share the same parent directory.

Check out a specific version tag

To build EmptyEpsilon from source in a manner compatible with official builds, ensure that you're on the official builds' codebase by checking out the corresponding release tag in both the EmptyEpsilon and SeriousProton repositories.

  • If you downloaded archives of EmptyEpsilon and SeriousProton source code from their GitHub releases pages, the archives contain only the downloaded version's codebase. You must download the same version of both EmptyEpsilon and SeriousProton.

  • If you used Git, you can view release tags in the GitHub repository or by running git tag --sort -v:refname. To check out the tag, use git checkout followed by the tag name, such as git checkout EE-2024.12.08 to checkout that release's tag.

    For example, to create builds which share the same codebase with the 2024.12.08 official builds, check out the corresponding release tag in both the SeriousProton and EmptyEpsilon repositories:

    cd SeriousProton
git checkout EE-2024.12.08
cd ../EmptyEpsilon
git checkout EE-2024.12.08

To define the version number used by EmptyEpsilon servers and clients to connect to each other, see Define the version number.

Prepare your build environment

To prepare to build the release, run cmake from the parent directory.

If you installed Ninja as recommended, run:

cmake -S EmptyEpsilon -B EmptyEpsilon/_build -G Ninja

If you're using Make instead, omit -G Ninja:

cmake -S EmptyEpsilon -B EmptyEpsilon/_build

If this step was successful, you can attempt to build EmptyEpsilon by running:

cmake --build EmptyEpsilon/_build

If successful, this builds an EmptyEpsilon binary in the EmptyEpsilon/_build directory. Depending on your operating system, you might also be able to build a distributable package by using the package target:

cmake --build EmptyEpsilon/_build --target package

The above steps as a single script:

git clone https://github.com/daid/EmptyEpsiloning
git clone https://github.com/daid/SeriousProton
cmake -S EmptyEpsilon -B EmptyEpsilon/_build -G Ninja
cmake --build EmptyEpsilon/_build --target package

If these steps fail, it's ok! Your operating system might require additional setup. For details, see the Build subpages for your operating system.

Run your build

If successful, the build steps resulted in an EmptyEpsilon binary (EmptyEpsilon.exe on Windows) located in the EmptyEpsilon/_build directory.

To run your build, the EmptyEpsilon binary must be run from a directory that contains the necessary game assets and resources. A distributable package includes those resources. If you built only the binary, for instance to quickly iterate on a new feature, you can use the repository's assets and resources by running the binary in the _build directory from the EmptyEpsilon directory.

On Linux, you can do this by running _build/EmptyEpsilon while in the EmptyEpsilon repository root directory. If you're in ~/git/daid from the build example, run:

cd EmptyEpsilon
_build/EmptyEpsilon

On Windows, copy EmptyEpsilon.exe from the _build directory to the EmptyEpsilon repository root and run it from there.

On macOS, its asset and resources path is relative to its location within an app bundle (.app). You might need to first package the app, codesign it, and then run the app package itself or launch the binary from within the app package. See Build ‐ macOS.

Distribute and install your build

If you used the --target package flag for cmake, this should also have created a distributable package. You can also execute the packaging step by running ninja package (or make package) from the _build directory.

On Linux builds, the package target generates a Debian package (EmptyEpsilon.deb) by default that depends on libsdl2 and libfreetype6. To install this package, run sudo dpkg --install EmptyEpsilon.deb.

You can also install the Linux build from the build step by using the install target: cmake --build EmptyEpsilon/_build --target install. This might require the use of sudo or administrative privileges.

For steps to build other Linux distribution package types, see Define the package type and that distribution's Build subpage.

On Windows builds, the default package target generates a ZIP archive (EmptyEpsilon.zip) containing the executable and all assets. You can unzip this package into its own folder and run EmptyEpsilon.exe from that folder. For more details, see Build ‐ Windows.

On macOS builds, the default package target generates an app bundle (EmptyEpsilon.app) that must be codesigned. For more details on creating a fully distributable disk image, see Build ‐ macOS.

Define build options

You can define additional build options by appending them with the -D flag after the cmake command to prepare your build environment.

For example, to set the build type to RelWithDebInfo, append -DCMAKE_BUILD_TYPE=RelWithDebInfo to that cmake command:

cmake -S EmptyEpsilon -B EmptyEpsilon/_build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo

Define the version number

To communicate with each other, the EmptyEpsilon server and all clients must share the same version number. This number appears on the main menu screen and in EmptyEpsilon.log.

By default, EmptyEpsilon defines the version number using the current compile date for the game's version number, regardless of the release you downloaded or tag you checked out. You must also override version numbering in the build scripts to set the version reported by EmptyEpsilon to the server.

Although servers and clients whose version numbers are defined as 0 bypass the version check, they might not function properly with each other if built from different codebases. Use version 0 builds for testing purposes only. Don't attempt to join a public game of EmptyEpsilon with one.

Define the version number using a CMAKE_PROJECT include file

The preferred method of setting a version number is to define the version in a CMake-syntax file and include it using the -DCMAKE_PROJECT_EmptyEpsilon_INCLUDE flag.

This file should contain CMake set statements for each version variable, and should be located somewhere in the project. For the 2024.12.08 example, the file's contents would be:

set(PROJECT_VERSION 2024.12.08)
set(PROJECT_VERSION_MAJOR 2024)
set(PROJECT_VERSION_MINOR 12)
set(PROJECT_VERSION_PATCH 8)

When running cmake, the path to the file is relative to the project (repository) root. Assuming you saved the file as version.cmake and it's located in ~/git/daid/EmptyEpsilon/, and you're running CMake from ~/git/daid, the cmake command you run from your build directory would include:

-DCMAKE_PROJECT_EmptyEpsilon_INCLUDE=version.cmake

To change the version number, update the contents of the version.cmake file, then re-run cmake. (Building with ninja re-runs CMake automatically.)

This method might cause issues with package generation; see https://github.com/daid/EmptyEpsilon/issues/2689. If that issue has been resolved, remove this line and the following paragraph from the wiki.

If you're building Debian or Fedora packages with this method, also define the package version number using CPACK_DEBIAN_PACKAGE_VERSION:

set(CPACK_DEBIAN_PACKAGE_VERSION 2024.12.08)
set(CPACK_RPM_PACKAGE_VERSION 2024.12.08)

Define the version number using CPACK_PACKAGE_VERSION numbers

A deprecated, but still working, method of setting the EmptyEpsilon version number is to add the following defines to the end of the relevant CMake command, after a space. For the 2024.12.08 example, the cmake command would be:

cmake -S EmptyEpsilon -B EmptyEpsilon/_build -G Ninja -DCPACK_PACKAGE_VERSION_MAJOR=2024 -DCPACK_PACKAGE_VERSION_MINOR=12 -DCPACK_PACKAGE_VERSION_PATCH=08

MAJOR should be the year, MINOR the month, and PATCH the day of the release date.

For an older discussion of options to set the version number, see issue #221.

Define debugging features

EmptyEpsilon has three primary build types: Release, RelWithDebInfo (release with debug info), and Debug. If no build type is specified, EmptyEpsilon defaults to Release. For details, see Build ‐ Debug.

A Debug build has additional visualizations and options for identifying issues in EmptyEpsilon, such as physics and GUI element border visualizations, but also performs relatively poorly.

To enable debug features in a build, define a CMAKE_BUILD_TYPE:

-DCMAKE_BUILD_TYPE=Debug

A RelWithDebInfo build behaves like a normal EmptyEpsilon release, but the resulting binary is larger because it contains debugging symbols useful to identifying issues with a debugger, such as GDB.

-DCMAKE_BUILD_TYPE=RelWithDebInfo

A Release build produces a smaller binary but is more difficult to debug.

-DCMAKE_BUILD_TYPE=Release

Define the package type

CMake uses the CPack packaging system to build packages, and CPack supports several package types. You can set the packaging type by defining CPACK_GENERATOR.

For example, to build Red Hat/Fedora packages, use the RPM generator:

-DCPACK_GENERATOR=RPM

Operating system build subpages

This wiki also has subpages with more detailed instructions for specific operating systems and build methods.

Windows

Build from source for a Windows target:

If builds fail with "Fatal error: Windows.h: No such file or directory", see discord/gamesdk-and-dispatch issue #100 for workarounds.

Linux

Build from source for a Linux target:

Android

Build ‐ Android

macOS/OS X

macOS builds are possible but not fully supported.

Build ‐ macOS

Add a custom footer

Clone this wiki locally