User:Eidolon/vcpkg Build Guide

This guide is a work in progress

Sonic Robo Blast 2 version 2.2.14 and Dr. Robotnik's Ring Racers feature a new, unified build system which leverages CMake, vcpkg and Ninja in order to configure and build the game from source in a consistent way. This was done in order to support a number of new requirements, including C++ support. This guide is written to aid developers setting up a build environment from scratch. It will only explain the necessary configuration for the 3 primary desktop platforms.

Note This guide is intended for experienced programmers as a reference for setting up a build environment, and not for beginners. It will not detail the behavior of any specific tool or how to program in C or C++. Please consult the documentation of the tools for more information or other learning material for programming in general.

Prerequisites

SRB2 minimally requires the following tools installed for all platforms:

• CMake 3.14 or higher
• The C and C++ toolchain and SDK for your platform, minimally supporting ISO C11 and ISO C++17 language standards
• git (optional for Linux)

Additionally, the CMake Presets (CMakePresets.json) used by the development team require the following:

• Ninja build system
• Microsoft vcpkg (optional for Linux)

The platform sections will detail the steps to obtaining them on each platform.

Windows Setup

Windows builds of SRB2 use the MinGW-w64 gcc toolchain distributed by MSYS2 and target i686 Win32. Dependencies are obtained and built from vcpkg, eliminating the cumbersome dependency setup of previous solutions. You will be setting up the toolchain and configuring your build directory accordingly; building without vcpkg is discouraged.

Developers targeting Windows will need to install MSYS2 and a number of packages within the MSYS2 environment.

Setting up MSYS2

1. Download and install MSYS2. You may elect to install via the official installer linked on MSYS2's homepage or set up a custom installation using their base packages. This guide will not detail additional steps for a custom installation.
2. Open MSYS MinGW 32-bit.
3. Ensure MSYS packages are up to date by running the command pacman -Syuu.
   • You may be prompted to install critical packages first and to restart MSYS shell; do so and run the command one more time to ensure everything is updated.
   • It is important to periodically update your MSYS installation by running this command occasionally, even after initial setup.
4. Install these necessary packages from pacman by running this command: pacman -S mingw-w64-i686-cmake mingw-w64-i686-ninja mingw-w64-i686-gcc
5. You may find it convenient to install the git package here as well. Git for Windows and MSYS git may coexist on the same system, but it is not recommended to share the PATH to Git for Windows with MSYS due to subtle incompatibilities in the Cygwin runtime used for each.

Setting up vcpkg

vcpkg is used to maintain a manifest of dependencies and obtain their sources to compile them directly with the same toolchain as is used to build the program. This alleviates problems arising from incompatible standard library linkage for toolchains, especially in the case of the C++ standard library, and greatly simplifies build environment setup.

1. Using git, clone the vcpkg repository somewhere on your system: git clone https://github.com/Microsoft/vcpkg. This clone should be reused between projects.
2. In the vcpkg directory in MSYS Shell, run scripts/bootstrap.sh -disableMetrics. This will download the current vcpkg executable.
3. In the Windows System settings, set the system environment variable VCPKG_ROOT to the path where vcpkg was cloned. Restart MSYS Shell after doing this. This will effectively make that checkout of vcpkg your global system installation of vcpkg.
4. To verify the installation is correct, run the following in MSYS Shell: $VCPKG_ROOT/vcpkg --version.

macOS Setup

To do write it

Linux Setup

To do write it

Building

In all cases, you will need to obtain the source for the project you are building. You can clone the development repository for SRB2 from https://git.srb2.org/STJr/SRB2 or get a release zip/tarball of the source for a specific version.

Building for Windows

There are several primary CMake presets to use when building for Windows

Preset	Description
ninja-x86_mingw_static_vcpkg-debug	No optimizations using Ninja as the build generator. DEVELOP is enabled in these builds, enabling runtime assertions and disabling IWAD hash checks. Statically linked.
ninja-x86_mingw_static_vcpkg-develop	Release optimizations but also with DEVELOP enabled. Statically linked.
ninja-x86_mingw_static_vcpkg-release	Build with release optimizations without DEVELOP enabled. Statically linked.

Each preset is configured to use its own build subdirectory in the path build/NAME_OF_PRESET. You do not need to set up a build directory.

These instructions assume you have vcpkg and CMake available and are running commands inside the MSYS MinGW 32-bit shell.

1. Run cmake --preset NAME_OF_PRESET
   • This step will take a while on first run, as vcpkg will download and compile the dependencies specified in the vcpkg.json, copy them to the build directory, and provide package modules for each to be found with find_package.
2. Run cmake --build --preset NAME_OF_PRESET

The built executable will be placed in build/NAME_OF_PRESET/bin/.

Building for macOS

To do write it

Building for Linux

To do write it

Running in Development

Running on Windows

To do write it

Running on Linux

To do write it

IDE support

VS Code

To do write it