Windows build environment: step‐by‐step instructions

Preamble

This page is intended for users looking for step-by-step instructions to set up a Windows build environment. If you are already proficient with Git and Unix shell in general, you will probably want to follow the Quickstart instead.

Quick primer

Recoil must be compiled to an executable (e.g. spring.exe) for it to actually run on a target platform (e.g. Windows), and the compilation process itself is actually easier from Linux for both Linux and Windows targets. In the past, this situation would have been handled with Linux virtual machines or a dual boot, but fortunately, nowadays we have access to WSL and Docker.

WSL (Windows Subsystem for Linux) allows developers to run a GNU/Linux environment directly on Windows. Under the hood, WSL is actually a lightweight virtual machine automatically managed by Windows, which automatically handles everything (such as how to transfer files between WSL and Windows).

Docker allows to build lightweight executable packages called container images, which include everything needed to run an application. In our case, it is used for the compilation toolchain.

In this tutorial, we will:

• Install prerequisites
• Clone Recoil in WSL
• Build Recoil for Windows from WSL
• Automatically using latest build in Windows game

Install prerequisites

Docker Desktop and WSL

• Download and install Docker Desktop for WSL 2.
• During the installation process, Docker Desktop will prompt you to install WSL 2. Follow the instructions.
• Once installed, launch Docker Desktop, go to Settings > General, and make sure Use WSL 2 based engine is enabled.

VS Code

• Download and install VS Code.
• When prompted to Select Additional Tasks during installation, make sure to check the Add to PATH option so you can easily open VS Code from WSL using the code command.
• Install the Remote Development extension pack.

Clone Recoil in WSL

• Open a Terminal and then run:

wsl
cd ~
git clone https://github.com/beyond-all-reason/spring -b BAR105 --recursive

• The Recoil repository is now cloned in WSL. You can access it in multiple ways:
  • From the Terminal: wsl and then cd ~/spring (shorthand for /home/<username>/spring).
    • You can then use code . to open the repository in a VS Code WSL window.
  • From the Windows File Explorer: navigate to \\wsl$\Ubuntu\home\<username>\spring (also available under Linux from the sidebar on the left).
    • Note that if you try to open \\wsl$\Ubuntu\home\<username>\spring in VS Code, a notification recommending you to switch to a WSL window will be displayed, with the option to Reopen Folder in WSL.

Build Recoil for Windows from WSL

First compilation

• Open a Terminal and then run:

wsl
cd ~/spring/docker-build
./init_container.sh
./build.sh

• This will take a long time.
• After the compilation is done, the build artifacts will be located in ~/spring/build-windows-64-RELWITHDEBINFO/install. Check that everything is sound by running the ls ~/spring/build-windows-64-RELWITHDEBINFO/install command, which should output something like this:

$ ls ~/spring/build-windows-64-RELWITHDEBINFO/install
AI              base           fonts       libIL.dll       libfontconfig-1.dll  libiconv-2.dll   libvorbis-0.dll      maps                  spring-headless.exe
LuaUI           cmdcolors.txt  games       libILU.dll      libfreetype-6.dll    libintl-8.dll    libvorbisenc-2.dll   pr-downloader.exe     spring.exe
OpenAL32.dll    ctrlpanel.txt  glew32.dll  libbz2.dll      libgcc_s_seh-1.dll   libogg-0.dll     libvorbisfile-3.dll  share                 springsettings.cfg
README-SDL.txt  doc            include     libcurl.dll     libglib-2.0-0.dll    libpcre-1.dll    libwinpthread-1.dll  socket.lua            unitsync.dll
SDL2.dll        examples       lib         libexpat-1.dll  libharfbuzz-0.dll    libpng16-16.dll  luaui.lua            spring-dedicated.exe  zlib1.dll

• Note the presence of spring.exe there. Congratulations, you now have successfully compiled Recoil!

Recompiling

Recompilations are much faster as the compilation cache is stored locally. After making changes in the repository (or switching to another branch, etc.), you can recompile by re-running ./build.sh in almost the same way as above:

wsl
cd ~/spring/docker-build
./build.sh

Note that ./init_container.sh does not need to be run again, ./build.sh will automatically detect if the container image is outdated and will tell you to run ./init_container.sh again when needed.

Let's try to make a simple change and recompile:

• From VS Code, open the file rts/System/SpringApp.cpp and Ctrl+F for InitWindow, then change the default window name to something else (e.g. HelloSpring).
• Now recompile using the instructions above, and notice how much faster it is.

Automatically using latest build in Windows game

The build artifacts located in WSL at ~/spring/build-windows-64-RELWITHDEBINFO/install can automatically be made available in your local Windows game environment by creating a symbolic link that points to them under <game directory>\data\engine\local-build, exploiting the fact WSL exposes them to Windows via \\wsl$\Ubuntu\home\<username>\spring\build-windows-64-RELWITHDEBINFO\install.

• Open a Powershell Terminal in administrator mode, and then run the following command replacing <game directory> and <username>:

New-Item -ItemType SymbolicLink -Path "<game directory>\data\engine\local-build" -Target "\\wsl$\Ubuntu\home\<username>\spring\build-windows-64-RELWITHDEBINFO\install"

• After the symbolic link has been created, the latest locally compiled engine build will always be available to use with the game.