How to compile Dr. Robotnik's Ring Racers for Windows

ℹ️ This guide is intended for Windows 10 x64, but should also apply for Windows 11.

⚠️ Your Windows Defender may be triggered when building the game.

This might happen because of certain files being generated during the compilation process.
If this does happen, you can safely allow the actions.

The following programs are required to proceed:

If these programs aren't installed, start with the Prerequisites section.
Otherwise, proceed directly to the Compiling section.

Prerequisites

1. Set up environment variables

One of the required packages, MSYS2, uses the $HOME environment variable.
To follow this guide accurately, you need to ensure that this variable exists on your system.

Ensure that any open Command Prompt or Windows PowerShell windows are closed.
Search for 'environment variables' in the Start Menu and select 'Edit environment variables for your account':

This will open the Environment Variables window, where you'll see the existing system environment variables.
Focus on the 'User variables' section.

If the HOME variable is already present, proceed to the next step.
If not, continue reading.
Click on the New... button. This will open a New User Variable window:

Add the HOME variable by filling out the form, as shown below:

Variable name: HOME

Variable value: C:\Users\<your username>

Replace <your username> with your actual username.
Click OK on the bottom-right when you're finished.
The HOME variable should be visible in 'User variables' section.

Click OK on the bottom-right to close the 'Environment Variables window.

If you're unsure, refer to the following video:

Adding the HOME environment variable

Variable name:	HOME
Variable value:	C:\Users\<your username>

2. Install Git

Download Git for Windows.

32-bit or 64-bit, depending on your operating system.
Follow each step in the setup wizard as instructed.

Leave each option set to its default value.
Open Windows PowerShell by searching for it in the Start Menu.

If you're unsure, refer to the following video:

Opening Windows PowerShell
Check if Git has been installed by running the following command in the terminal:
```
git --version
```
If successful, you should see a message like this in your terminal:

Keep this terminal open for the next step.

3. Install vcpckg

At this point, a PowerShell terminal should be open, defaulting to your home directory (C:\Users\<your username>), as shown here:

If you haven't got Windows PowerShell open, follow these instructions.
Clone the vcpkg repository into a folder of your choice using Git, by running the following command in your terminal:
```
git clone https://github.com/microsoft/vcpkg.git
```
This will create a folder in your home directory named vcpkg, therefore, the full path of the repository should be:
```
C:\Users\<your username>\vcpkg
```
Navigate to the newly-created vcpkg folder and run the bootstrap script:
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
Check if vcpkg has been installed by running the following command:
```
.\vcpkg --version
```
If successful, the terminal will display the version of vcpkg that has been installed:

If you're unsure, refer to the following video:

Installing vcpkg

4. Install MSYS2

Download the MSYS2 installer.
Follow each step in the setup wizard as instructed.

Leave each option set to its default value.
Once installation completes, a terminal window will open. This confirms that MSYS2 was installed succesfully.

You may now close this window and proceed to the Compiling instructions.

If you're unsure, refer to the following video:

Installing MSYS2

Compiling

1. Opening MSYS2

ℹ️ Copy (Ctrl+C) and paste (Ctrl+V) shortcuts do not work inside MSYS2 shells. You can still right-click to copy and paste.

Using File Explorer, navigate to the default MSYS2 installation folder: C:\msys64.
Open the MINGW32 shell (mingw32.exe), as denoted by the icon.

The MINGW32 shell is a terminal provided by MSYS2.

Like PowerShell, this terminal opens in your home directory by default (C:\Users\<your username>).
As represented by the tilde symbol (~).

If you're unsure, refer to the following video:

Opening the MINGW32 shell

2. Updating the package database

Update the package database and all installed packages by running the following command in the shell:
```
pacman -Syu
```
When prompted with Proceed with installation? [Y/n], ype Y in the terminal and press Enter.
After updating, you might see a message prompting you to close the terminal window, like this:
```
To complete this update all MSYS2 processes including this terminal will be closed. Confirm to proceed [Y/n]
```
If you don't see this message, continue to the next step.

If you do, type Y in the terminal and press Enter.
To open the terminal window again, follow the instructions in step 1.

3. Installing the required packages

In the MINGW32 shell, execute the following command to install all the required packages:
```
pacman -S make git mingw-w64-i686-gcc mingw-w64-i686-ninja mingw-w64-i686-cmake
```
When prompted with:
```
Proceed with installation? [Y/n]
```
Type Y in the terminal and press Enter.
Wait for the packages to finish downloading.
To verify that all the required packages have been installed sucessfully, run the follow command in the terminal:
```
which ninja make cmake gcc g++ git
```
If the packages have been installed succesfully, each command will return the path to its respective executable:

Keep this terminal open for the next step.

4. Downloading the game's source code

ℹ️ For demonstration purposes, this guide will use the latest version of Dr. Robotnik's Ring Racers. As of January 1st 2025, that is v2.3.

Verify that the terminal is in your home directory by running the following command:
```
cd $HOME
```
The tilde symbol (~) represents your home directory.
Clone the repository for Ring Racers, with the following command:
```
git clone https://github.com/KartKrewDev/RingRacers.git RingRacersRepo
```
This will create a new folder in your home directory named RingRacersRepo, which will contain the game's source code.

If you're unsure, refer to the following video:

Cloning the repository
Navigate to the new RingRacersRepo folder by running the command:
```
cd RingRacersRepo
```
Switch the current branch to v2.3 with the following command:
```
git checkout v2.3
```
If you encounter any errors when running this command, make sure that you're in the RingRacersRepo folder.
Refer to the previous step for instructions.
Verify that your branch is set to v2.3, by running:
```
git branch
```
You will see an asterisk (*) next to the current branch, which should say (HEAD detached at v2.3).

Keep this terminal open for the next step.

5. Configuring the game for compilation

Set the VCPKG_ROOT environment variable by running the following:^⭐
```
export VCPKG_ROOT="$HOME/vcpkg"
```
Configure the game for building with this command:
```
cmake --preset ninja-x86_mingw_static_vcpkg-release
```
cmake will begin configuriation and grab all the required dependecies needed to compile the game via vcpkg.

Since this is your first time running the configuration, it may take some time, so be patient.
Future configurations will be faster.
If configuration completes successfully, you should see messages in the terminal like this:
```
-- Configuring done (376.5s)
-- Generating done (0.3s)
-- Build files have been written to: C:/Users/<your username>/RingRacersRepo/build/ninja-x86_mingw_static_vcpkg-release
```
Keep this terminal open for the next step.

^⭐ To avoid having to do this all the time, you can set VCPKG_ROOT as an environment variable permanently with the following command:
```
echo 'export VCPKG_ROOT="$HOME/vcpkg"' >> ~/.bashrc
```

6. Compiling the game

To begin compiling, run the following command in the terminal:
```
cmake --build --preset ninja-x86_mingw_static_vcpkg-release
```
cmake will finally begin the build process, compiling the source files required to build the game's executable.
Depending on your computer's hardware, this can either be quick or take some time.

If you're unsure, refer to the following video:

Compiling the game with cmake
If the game has succesfully compiled, you should see a message in the terminal similar to this:
```
[475/475] Linking CXX executable bin\ringracers_v2.3.exe
```
This line confirms that the build process has completed and the executable has been succesfully created.
The executable can be found in the build directory:
```
build/ninja-x86_mingw_static_vcpkg-release/bin
```
This path is relative to the RingRacers directory. The terminal opens in your home directory by default (C:/Users/<your username>).
Therefore, the full path to your compiled game would be:
```
C:\Users\<your username>\RingRacersRepo\build\ninja-x86_mingw_static_vcpkg-release\bin\ringracers_v2.3.exe
```
To run the executable, you need to copy it to the folder where you've already installed Dr. Robotnik's Ring Racers.