Network Distribution

Overview

FASTBuild can scale compilation across the network to utilize additional CPU power to speed up a build. Distribution is supported for all major compilers, but has some restrictions/requirements:

Distribution requires:

Compatible compilation settings
Compiler Synchronization Setup
Configuration of worker discovery
Starting the worker process
Activation of distributed compilation

Compilation Settings

Some compilation settings (listed below) are incompatible with distribution. If FASTBuild detects one of these incompatible settings, it will automatically build the impacted object(s) locally. A build can safely mix distributable and non-distributable objects.

GCC/SNC/Clang

-ftest-coverage (and --coverage) cannot be distributed: .gcno files would contain wrong paths, .gcda files would be created in a wrong place.

MSVC

/ZW (Consume Windows Runtime) cannot be used.
Precompiled Headers cannot be distributed. (Objects using PCH can be distributed.)
/clr (Managed C) cannot be distributed due to bugs in the Microsoft compiler's preprocessor.
/analyze cannot be distributed due to inconsistencies in the Microsoft compiler's preprocessor.

Compiler Synchronization

FASTBuild will synchronize the compiler toolchain to the remote machine in an isolated environment. This avoids the need to install the toolchain on the remote machine, and ensures you are always compiling with the correct compiler. To do this, FASTBuild needs to know which files to synchronize over the network. See the Compiler() function documentation for details.

Worker Discovery

Workers are discovered through a brokerage location. The brokerage location is a network path accessible from both the host and workers. The brokerage path is configured by:

Setting the FASTBUILD_BROKERAGE_PATH Environment Variable

Windows and UNC format paths are supported.

Workers signal their availability by writing a token to this location. Clients discover workers by checking this location.

Starting a Worker

A worker is started by running the FBuildWorker.exe. With a configured Brokerage Path, it will signal its availability to clients.

Activation of Distribution

To start a distributed build, add -dist on the command line. Any distributable tasks will be passed to available workers.