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 git

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

Unlike Windows and macOS, the only thing you need to do is configure and run.

Preset	Description
ninja-debug	No optimizations, using Ninja.
ninja-develop	Release optimizations, DEVELOP enabled.
ninja-release	Release optimizations, release mode

1. cmake --preset ninja-release
2. cmake --build --preset ninja-release

Running in Development

Running on Windows

To do write it

Running on macOS

To do write it

Running on Linux

Obtain the assets bundle for the game, and export the environment variable to override where the game searches for assets.

Game	Environment variable
SRB2	SRB2WADDIR
SRB2Kart	SRB2WADDIR
Ring Racers	RINGRACERSWADDIR

The binary will be located in the bin directory of the preset's build directory.

Example shell command: RINGRACERSDIR=/path/to/ringracers/data build/ninja-debug/bin/ringracers

IDE support

CMake gives a few easy affordances for being used in an IDE, unlike makefiles.

clangd general

Passing -DCMAKE_EXPORT_COMPILE_COMMANDS=ON to the configure step on any platform will make CMake export a compile_commands.json file in the target's build directory. For example, in build/ninja-debug/compile_commands.json. This can be provided to the clangd language server to provide IntelliSense features to editors that support it.

.clangd is the file used to configure clangd language server. See the clangd Configuration Documentation for details. Make sure this file is not included in your commit trees.

CompileFlags:
  CompilationDatabase: build/ninja-debug

VS Code

The VS Code extension CMake Tools can be used to configure a CMake build directory specifically for use with VS Code. VS Code will automatically configure the debugger and add a run task that will build through CMake, using the clangd compile_commands.json to provide IntelliSense features. This can be configured to make building and debugging with the correct environment variables a one-click operation.

If you are developing on Windows, you will need to make sure that a User-Local Kit is available to tell CMake where your compilers are. CMake Tools provides (incomplete) documentation for how to configure Kits.

Here is a snippet Kit you can insert after running the command CMake: Edit User-Local Kits (under different names for other languages). Note that you may need to adjust the given paths to point to your MSYS2 installation if you chose something other than the defaults. Make sure that this Kit is selected when configuring CMake.

{
  "name": "MSYS2 MinGW i686",
  "environmentVariables": {
    "CMT_MINGW_PATH": "C:/msys64/mingw32/bin"
  },
  "compilers": {
    "CXX": "C:/msys64/mingw32/bin/g++.exe",
    "C": "C:/msys64/mingw32/bin/gcc.exe"
  },
  "preferredGenerator": {
    "name": "Ninja"
  }
}

Finally, you will need to edit your VS Code Workspace settings. This is usually located at .vscode/settings.json, but if your Workspace is configured elsewhere, you can also use the command Preferences: Open Workspace Settings (JSON) to open it in an editor tab. Again, change the filesystem paths as necessary.

{
  "cmake.configureSettings": {
    "CMAKE_TOOLCHAIN_FILE": "C:/path/to/your/vcpkg/scripts/buildsystems/vcpkg.cmake",
    "VCPKG_HOST_TRIPLET": "x86-mingw-static",
    "VCPKG_TARGET_TRIPLET": "x86-mingw-static",
    "SRB2_CONFIG_DEV_BUILD": true
  },
  "cmake.environment": {
    "VCPKG_ROOT": "C:/path/to/your/vcpkg"
  },
  "cmake.buildDirectory": "${workspaceFolder}/build-vscode",
  "cmake.debugConfig": {
    "args": ["-noexchndl", "-win"],
    "cwd": "C:/path/to/game/assets",
    "environment": [
      {
        "name": "SRB2WADDIR",
        "value": "C:/path/to/game/assets"
      }
    ]
  },
  "cmake.useCMakePresets": "never",
  "cmake.cmakePath": "C:/path/to/cmake/bin/cmake.exe"
}

It is strongly recommended to add the build-vscode path (or whichever build directory name you choose to use) to your local repository's exclude file so Git does not try to include it. See the Git reference manual on gitignore for details. You can add that in a terminal with this command. echo "/build-vscode" >> .git/info/exclude Merge requests and patches which include build directories or other build artifacts will be summarily rejected.

We pass -noexchndl in the args to avoid having to copy exchndl.dll and family from Dr. Mingw to the cmake bin directory. You may also find it useful to have your assets and working directory as separate paths in order to keep your development game data (e.g. saves, profiles) separate from your release data.