SpringRTS Build Environment (Docker)

Introduction

There is a docker image available that is based on Ubuntu being able to compile the engine. The image can be used as a one-shot command to compile the engine and provide the artifacts by a docker volume but it can also be used as a development environment.

Docker Image

Build your own container image (might take a while):

1. Checkout the repository, change into the directory docker-build and build the image yourself using the command: ./init_container.sh. Additional arguments can be passed to configure the image creation process (see below).

2. When building the image the following arguments are available (outdated info, UPDATE):

Parameter	Default	Description
mxe_version	02852a7b690aa411ce2a2089deea25a7292a33d6	Version of MXE to use. This can be a commit hash but also a tag or branch name
mxe_gcc	gcc11	Defines which gcc plugin to use in MXE
cmake_version	3.16.*	Defines a CMake version string to be used when installing CMake via pip
ccache_version	v4.5.1	Version of ccache to use. This can be a commit hash but also a tag or branch name

Quickstart

Preparation

git clone https://github.com/beyond-all-reason/spring
cd spring
https://github.com/beyond-all-reason/spring
git submodule init && git submodule update
git submodule update --init --recursive

Building

To build branch BAR105 from https://github.com/beyond-all-reason/spring (default values) run this command:

cd docker-build
./init_container.sh #if not done before
./build.sh -p linux-64
./build.sh -p windows-64

A more complex example (see parameters section):

./build.sh -p linux-64 -t RELWITHDEBINFO -C -DTRACY_ENABLE=1 -k

The output artifacts can be found in a volume linked to the container. Accessible e.g. via the Docker Desktop application.

Develop

To start a development environment: docker run -it springrts-build dev

You will get a bash shell with the spring source code checked out ready to make modifications and compile by typing make or cmake --build .:

----------------------------------------------
SpringRTS development environment has been set up successfully
Source code directory: /spring
Build directory: /spring/build
----------------------------------------------
<springdev> root@e0d3fbe4fffd:/spring/build$ _

Troubleshooting Build Errors

- Running docker as non-root user

If the ./init_container.sh step fails with permission denied, make sure to run docker as a non-root user.

- Out of memory; signal killed terminated program

If running in a virtual machine and the ./build.sh command exists with a killed signal terminated error, make sure the virtual machine has at least 12GB of memory.

- Delete artifacts on build failure

If a build fails for any reason, make sure to delete the docker artifacts before trying to run the ./build.sh command again.

General

The image is based on Ubuntu 18.04 so created Linux binaries are runnable on that version and later. Windows binaries are build using a MXE cross-compile environment.

The image utilizes ccache to speedup consecutive compilation processes. It is recommended to reuse the cache data in different containers by configuring the ccache volume accordingly.

The image can be used with different commands that are described below:

1. build
2. dev
3. shell (just open a bash shell)

The build process consists of multiple steps. Each step is represented by a shell script and they are run consecutively:

1. 00_setup.sh
2. 01_clone.sh
3. 02_configure.sh
4. 04_fill_portable_dir_linux-64.shand 04_fill_portable_dir_windows-64.sh
5. 05_fill_debugsymbol_dir.sh
6. 06_fill_build_options_file.sh
7. 07_pack_build_artifacts.sh
8. 08_copy_to_publish_dir.sh

Parameters

Both commands can be configured with these arguments:

Parameter	Default	Description
-p	windows-64	Which target platform to setup build for (use "linux-64" or "windows-64")
-t	RELWITHDEBINFO	Build type: RELWITHDEBINFO (default), DEBUG, RELEASE, PROFILE
-C	<empty>	additional cmake flags. eg. -C -DTRACY_ENABLE=1. Multiple flags can be passed by specifying the flag multiple times.
-k	false	whether to pack and publish artifacts to the ${buildfolder}/publish dir.
-s	1	Enable stripping of symbols from artifacts
-b	BAR105	The branch to build from the spring project. Only relevant if you set -l to false
-u	https://github.com/beyond-all-reason/spring	URL to a Spring Git repository. Only relevant if you set -l to false
-a	https://github.com/beyond-all-reason	Prefix for the URLs used to clone auxiliary repos. The following URL will e.g. be cloned: https://github.com/beyond-all-reason/BARbarIAn
-c	<empty>	Configures gcc's -march and -mtuneflag
-d	0	Dummy mode: to not actually clone or compile but just produce zero-size artifacts
-e	1	Enable ccache
-f	<empty>	CXXFLAGS and CFLAGS flags for gcc
-l	true	whether this build is a local build. If false, artifacts will be published and repo branch will be cloned out.
-o	false	Disable headless and dedicated builds, default off
-r	depends on built type	CXX flags override for selected build type
-w	true	suppress outdated container warning
-z	false	Enable generation ccache debug data in /ccache_dbg

Building (command run)

The container can be started by passing run as the first parameter to run the compilation process for one target platform and produce an archive package that will contain the runnable engine with all library dependencies.

The following directories contain output data and can be used as a volume to access the files:

1. /publish - This is the directory the build process will copy all produced artifacts into
2. /ccache - The image is using ccache to speed up the build process. To make use of the cache you have to run different build runs using the same cache data directory.
3. /ccache_dbg - Directory where ccache debug data will be placed

docker run -v D:\myspringbuild:/publish -it springrts-build

Building from another GitHub Repository

Build branch `gl4` from repository at `https://github.com/beyond-all-reason/spring`:
docker run -it springrts-build build -u https://github.com/beyond-all-reason/spring -b gl4 -p linux-64

Development

The image can also be used as a development environment. When starting the development mode then only the first three steps are executed:

1. 00_setup.sh
2. 01_clone.sh
3. 02_configure.sh

So the source code will be cloned into the container and the build will be configured using CMake. You will find yourself inside the development shell ready to start the compilation process. In you started the container with a raw /bin/bash shell (didn't use build or dev command) you can start the dev shell manually by running dev.sh with the usual arguments.

When working in the development shell you can always start the step scripts manually if needed. But be aware that running e.g. 01_clone.sh will wipe the /spring directory completely and create a clean checkout. So make sure to not lose your changes! As some of the steps will modify shell variables all scripts should be sourced (instead of started regularly), e.g. . /scripts/01.clone.sh.

Reconfiguring

In case you want to switch the configuration inside the development shell you you can run 00_setup.sh <arga>.

For example:

. /scripts/00_setup.sh -p linux-64