Command Line Options

FBuild.exe

Option Summary
-cache[read|write] Use the build cache.
-cachecompressionlevel [level] Control compression level of cache entries. (Default -1)
-cacheinfo Emit summary of objects in the cache.
-cachetrim [sizeMiB] Reduce the size of the cache.
-cacheverbose Provide additional information about cache interactions.
-clean Force a clean build.
-compdb Generate JSON compilation database for the specified targets.
-config <path> Explicitly specify the config file to use.
-continueafterdbmove Allow build to continue after a DB move.
-dbfile <path> Explicitly specify the dependency database file to use.
-debug [Windows Only] Allow attaching a debugger immediately on startup.
-dist Enable distributed compilation.
-distcompressionlevel [level] Control compression level of jobs sent out for distribution. (Default -1)
-distverbose Enable detailed logging for distributed compilation.
-dot[full] Generate an fbuild.gv DOT file for known dependencies.
-fixuperrorpaths Reformat GCC/SNC/Clang error messages in Visual Studio format.
-forceremote Force distributable jobs to only be built remotely.
-help Show usage help.
-ide Enable multiple options for IDE integration.
-j[x] Explicitly set local worker thread count.
-monitor Output a machine readable file for use by 3rd party tools.
-nofastcancel Disable aborting other tasks as soon any task fails.
-nolocalrace Disable local race of remotely started jobs.
-noprogress Don't show the progress bar while building.
-nostoponerror Don't stop building on first error.
-nosummaryonerror Don't print the -summary output if there is an error.
-nounity Individually build all files normally built in Unity.
-profile Output a Chrome tracing format fbuild_profile.json describing the build.
-progress Show the build progress bar even if it would otherwise be disabled.
-quiet Don't show build output.
-report=[html|json] Output a report at build termination. (Default html)
-showcmdoutput Show output of external processes.
-showcmds Show command lines used to launch external processes.
-showdeps Show known dependency tree for specified targets.
-showtargets Show primary build targets, excluding those marked "Hidden".
-showalltargets Show primary build targets, including those marked "Hidden".
-summary Show a summary at the end of the build.
-verbose Show detailed diagnostic information for debugging.
-version Print version and exit.
-vs [Deprecated] Same as -ide.
-wait Wait for a previous build to complete before starting.
-why For each item that builds, show the trigger reason.
-wrapper Wrapper mode for Visual Studio. (Windows only)
-wsl [wslPath] [args...] Invoke a command inside the Windows Subsystem for Linux.

FBuildWorker.exe

Option Summary
-console Disable UI. (Windows Only)
-cpus=[n|-n|n%] Control worker CPUs allocation.
-debug [Windows Only] Allow attaching a debugger immediately on startup.
-minfreememory=[MiB] [Windows Only] Override the default minimum memory limit (in MiB).
-mode=[disabled|idle|dedicated|proportional] Control worker availability.
-nosubprocess Don't spawn as a sub-process.
-periodicrestart Restart worker every 4 hours.

FBuild.exe Detailed

-cache[read|write]

Enable usage of the build cache. The cache options need to be configured in the build configuration file.

The cache can be enabled as read only or write only with '-cacheread' or '-cachewrite'. This can be useful for automated build systems, where you might like one machine to populate the cache for read-only use by other users.

Use of '-cache' is equivalent to '-cachread' and '-cachewrite' together.

-cacheinfo

Emit summary of objects in the cache. This can be used to understand the total size of the cache and how quickly it is growing. (See the related -cachetrim)

-cachecompressionlevel [level]

Control compression level of items stored in the cache. (Default 1)

This can be used to increase the level of compression, trading increased CPU time when storing to the cache in order to reduce network transfer and storage. This can be useful in network bandwidth limited environments. Since decompression speed remains fairly constant, an increase in compression time may also be a worthwhile trade-off for environments that populate a cache once for many users to consume (an automated build environment for example).

This can also be used to reduce the level of compression, with the reverse considerations. This can be useful in CPU limited environments with high network bandwidth availability.

LevelDescription
-128 to -1LZ4 compression. Lower values are faster but compress less. Default is -1.
0Compression is disabled.
1 to 12Zstd compression. Higher values compress more, but are slower.

Timings will vary depending on hardware and objects being cached, but example timings compressing a ~4.3MiB object file is as follows:

File : Tools/FBuild/FBuildTest/Data/TestCompressor/TestObjFile.o Size : 4328135 Compression Decompression Level | Time (ms) MB/s Ratio | Time (ms) MB/s ------------------------------------------------ LZ4: 0 | 0.469 8792.0 1.00 | 0.383 10767.3 -256 | 1.237 3337.8 1.24 | 0.526 7845.0 -128 | 1.515 2724.1 1.42 | 0.605 6827.9 -64 | 2.103 1963.1 1.70 | 0.757 5453.7 -32 | 2.550 1618.5 2.06 | 0.838 4924.7 -16 | 2.740 1506.2 2.36 | 0.921 4480.6 -8 | 3.330 1239.6 2.80 | 1.047 3942.8 -4 | 3.540 1166.1 3.09 | 0.973 4240.5 -2 | 3.609 1143.7 3.23 | 1.008 4094.3 -1 | 3.597 1147.5 3.29 | 1.053 3918.5 1 | 4.950 833.9 5.35 | 3.325 1241.2 <--- Default 3 | 7.022 587.8 5.49 | 3.383 1220.2 6 | 20.791 198.5 5.79 | 3.175 1300.2 9 | 32.680 126.3 6.00 | 3.105 1329.2 12 | 81.778 50.5 6.03 | 3.048 1354.0

-cachetrim [sizeMiB]

Reduce the size of the cache to the specified size in MiB. This will delete items in the cache (oldest first) until under the requested size. (See the related -cacheinfo)

-cacheverbose

Provide additional information about cache interactions, including cache keys, explicit hit/miss/store information and performance metrics. This can be used to assist troubleshooting.

-clean

Force a clean build. The build configuration file is re-parsed and all existing dependency information is discarded. A build is performed as if building for the first time with no built files present.

-compdb

Instead of building specified targets generate a JSON compilation database for them. Resulting compilation database will include entries for all source files from ObjectList and Library nodes that are dependencies of the specified targets.

-config <path>

Explicitly specify the config file to use. By default, FASTBuild looks for "fbuild.bff" in the current directory. This options allows a file to be explicitly specified instead.

-continueafterdbmove

Allow build to continue after a DB move.

FASTBuild's database is tied to the directory in which it was created and cannot be moved. If a move is detected, an error will be emitted. -continueafterdbmove allows the build to continue after this error has been emitted, ignoring and replacing the DB file.

-dbfile <path>

Explicitly specify the dependency database file to use. By default, FASTBuild will load and save its dependency database in the same directory as the config file (with a ".platform.fdb" suffix). This option allows the file to be explicitly specified instead.

-debug

[Windows Only] Display a message box on startup to allow a debugger to be attached. Can be useful if triaging problems with FASTBuild that can't be reproduced in the debugger.

-dist

Enable distributed compilation. Requires some build configuration.

-distcompressionlevel [level]

Control compression level of jobs sent out for distribution. (Default -1)

This can be used to increase the level of compression for jobs sent out for distribution, trading increased CPU time in order to reduce network transfer. This can be useful in network bandwidth limited environments. Note that this value does not affect the compression level of the responses sent back from workers.

LevelDescription
-128 to -1LZ4 compression. Lower values are faster but compress less. Default is -1.
0Compression is disabled.
1 to 12LZ4 HC compression. Higher values compress more, but are slower.

Timings will vary depending on hardware and source code being preprocessed, but example timings compressing a ~1.8MiB flattened source file are as follows:

File : Tools/FBuild/FBuildTest/Data/TestCompressor/TestPreprocessedFile.ii Size : 1802697 Compression Decompression Level | Time (ms) MB/s Ratio | Time (ms) MB/s ------------------------------------------------ 0 | 0.289 5943.6 1.00 | 0.283 6066.8 -256 | 0.992 1733.7 1.25 | 0.291 5912.9 -128 | 1.059 1622.8 1.44 | 0.345 4977.0 -64 | 0.955 1799.8 1.86 | 0.448 3837.0 -32 | 1.179 1457.7 2.53 | 0.508 3384.4 -16 | 1.348 1274.9 3.37 | 0.553 3106.3 -8 | 1.442 1192.3 4.05 | 0.542 3169.7 -4 | 1.517 1132.9 4.53 | 0.537 3198.9 -2 | 1.559 1102.6 4.80 | 0.620 2772.5 -1 | 1.612 1066.7 4.94 | 0.557 3085.1 <--- Default 1 | 5.791 296.9 6.27 | 0.509 3380.1 3 | 6.875 250.1 6.44 | 0.496 3468.7 6 | 13.767 124.9 6.67 | 0.613 2804.2 9 | 34.530 49.8 6.72 | 0.503 3419.4 12 | 122.061 14.1 6.82 | 0.512 3360.6 ------------------------------------------------

-distverbose

Print detailed information about distributed compilation. This can help when investigating connectivity issues. Activates -dist if not already specified.

-dot[full]

Generate an fbuild.gv DOT file for known dependencies which can be visualized in various third party tools such as Graphviz.

Example:

fbuild.exe -dot Game-x86-Debug

If no target is specified, "all" is used.

By default, all leaf FileNodes (typically source files) are pruned from the graph. A full graph can be emitted by using -dotfull.

NOTE: The dependencies shown will reflect the state as of the last completed build. i.e. dependencies that would be discovered during the next build will not be shown.

NOTE: Large graphs may not be handled well by some visualizers.

-fixuperrorpaths

Enables re-formatting of warnings, errors and notes for GCC/SNC & Clang to Visual Studio format. Additionally, relative paths are expanded to full paths. This allows these errors to be double-clickable inside Visual Studio.

Enabled automatically when '-vs' is used.

-forceremote

Prevents all local compilation of distributable jobs.

FASTBuild will normally utilize local CPU resources to compile distributable jobs in several situations, in order to improve performance:

  • When there are no remote workers available (otherwise build would not complete)
  • When all remote workers are busy and local CPUs would be idle
  • When blocked on remote work

This option prevents local consumption of distributable jobs in all these cases. This will generally result in slower builds and may even prevent the build completing entirely. As such, this options should generally only be used for troubleshooting.

Additionally, this option disabled use of the cache.

NOTE: This option can prevent builds from completing (if no workers are available for example).

NOTE: This option will generally degrade build performance.

-help

Prints command line usage information, as per the summary at the top of this page.

-ide

IDE integration mode. Enables several options that are commonly desired when running from within an IDE such as VisualStudio, XCode or kDevelop. The following options are enabled:

-j[x]

Generally, the default behaviour will give best performance, and this option should only be used in very specific situations.

The -j[x] option allows you to artificially control local parallelism by modifying the local thread pool size.

FASTBuild will normally determine the optimal number of local threads to use by detecting the number of hardware cores present on the host. The -j option allows you to override this.

Positive values for x can be used to set the number of tasks which can be performed locally in parallel. This can be used to limit CPU usage on a machine that needs to perform other work while compilation is in progress. Values greater than the number of physical processors are also accepted, but will almost always result in degraded performance.

A value of 0 for x indicates that no additional threads should be spawned, and build graph processing and compilation should occur on the same thread. This can be useful for build process debugging, especially when combined with the '-verbose' option.

This option has no direct bearing on distributed compilation, but modifying local parallelism will reduce the ability of FASTBuild to distribute work efficiently.

-monitor

Output a machine readable file for use by 3rd party tools.

A machine readable file is written to %TEMP%/FastBuild/FastBuildLog.log and updated throughout the build. This file can be monitored by 3rd party applications to provide enhanced visualization of the build state.

-nofastcancel

Disable aborting other tasks as soon any task fails.

Normally, when a task fails, any tasks running on other threads are aborted (external processes are terminated), allowing builds with errors to fail quickly. If this behavior is undesirable, it can be disabled with -nofastcancel. If "fastcancel" is disabled, any already started tasks will be allowed to complete.

-nolocalrace

Disable local race of remotely started jobs. This can be useful for debugging.

NOTE: This option can prevent builds from completing (if remote workers become unresponsive for example).

NOTE: This option will generally degrade build performance.

-noprogress

Suppresses the progress bar that is normally shown while compiling.

This should be used when targetting compilation from within Visual Studio or another IDE. (or use -vs)

-nostoponerror

When encountering build errors, FASTBuild will normally stop as quickly as possible.

-nostoponerror instructs FASTBuild to instead build as much as possible before stopping when failures occur. This is useful if you want to see as many errors as possible in your compilation output.

NOTE: When specifying multiple targets to compile on the command line, -nostoponerror is implied.

-nosummaryonerror

The -nosummaryonerror option instructs FASTBuild to only print the -summary overview if the build completes successfully.

NOTE: When specifying -nosummaryonerror, -summary is implied if not already specified.

-nounity

Individually build all files normally in Unity.

All files specified in Unity will instead be built as if specified individually outside of Unity.

-profile

Output a Chrome tracing format fbuild_profile.json describing the build.

When "build profiling" is activing, scheduling information for items (local and remote) is recorded to an fbuild_profile.json file. This file is written at the very end of the build, and can be viewed in Chrome's profiling viewer (chrome://tracing).

NOTE: This may have a small impact on build performance.

-progress

Show the build progress bar even if it would otherwise be disabled.

FASTBuild shows a build progress bar unless it detects that the stdout has been redirected (indicating that it's not being run from a command prompt). You can override this behavior and force the progress bar to be enabled using -progress.

-quiet

Don't show build output. Information about which items are being built and the overall state of the build will be suppressed.

-report=[html|json]

Output a detailed report at the end of the build. The report is written to a report.html or report.json file (default html if no option given) in the current directory.

The build report contains details of:

  • The build environment (version, cmd line used etc.)
  • All items built.
  • Cache utilization.
  • Include file usage.

NOTE: This option will lengthen the total build time, depending on the complexity of the build.

-showcmdoutput

Displays the full output of external processes regardless of outcome.

Normally FASTBuild suppresses the output of external processes unless there are warnings or failures. In some cases (for debugging for example), it can be useful to see the complete output.

NOTE: This option may have an impact on build performance.

-showcmds

Displays the full command lines passed to external tools as they are invoked.

This option is useful for debugging build configurations, where the -verbose mode is too spammy.

NOTE: This option may have an impact on build performance.

-showdeps

Displays the hierearchy of dependencies for the specified target(s). This can be useful for debugging build configurations.

Example:

fbuild.exe -showdeps Game-x86-Debug

If no target is specified, "all" is used.

NOTE: The dependencies shown will reflect the state as of the last completed build. i.e. dependencies that would be discovered during the next build will not be shown.

-showtargets

Displays the list of targets defined in the bff configuration file, excluding those which have the .Hidden property set.

-showalltargets

Displays the list of targets defined in the bff configuration file, including those which have the .Hidden property set.

-summary

Displays a summary upon build completion.

-verbose

Show detailed diagnostic information for debugging.

This can be used to provide more information when debugging a build configuration problem. It will display detailed information as the build configuration is parsed, as well as detailed information during the build, including full command line arguments passed to external executables.

It is usually useful to combine this flag with -j0 to serialize the build process and output (avoiding the output of different threads being mixed together).

-version

Prints executable version information and exits. No configuration parsing or building is performed.

-vs

[Deprecated] VisualStudio mode - same is -ide. Use -ide instead.

-wait

Queue build after an already running build completes.

Only one instance of FASTBuild can run at a time within the same root working directory. If you launch another FASTBuild while one is already running, the error "Another FASTBuild is already running." will be emitted.

If you wish to build multiple targets, you should specify them together on the command line. This allows for parallelization across both targets.

Alternatively, the -wait command line arg allows you to queue the second build, so instead of failing, it will start after the first build completes. This will be slower than if both targets were invoked together on the original command line.

-why

While building, the reason for each item being built is shown. This can be useful for diagnosing unexpected dependencies.

-wrapper (Windows Only)

Spawns FASTBuild via an intermediate sub-process to be able to cleanly terminate a build from Visual Studio.

When canceling a build in Visual Studio, the FASTBuild process will be killed, with no opportunity to save the build database, resulting in lost compilation work. Specifying this option spawns an orphaned child process to do the actual work. When the parent process is terminated by Visual Studio, the child process detects this and cleanly shuts down.

If a subsequent "wrapper mode" build is initiated before the first terminates, FASTBuild will wait for this first process to complete.

-wsl [wslPath] [args...] (Windows Only)

Invoke a command inside the Windows Subsystem for Linux.

It doesn't seem to be possible to invoke wsl.exe directly from Visual Studio as a BuildCommand. To allow this to be possible, FASTBuild can act as a forwarder using the -wsl command line option. This can be used to run the Linux version of FASTBuild for example.

Example:

fbuild.exe -wsl c:\Windows\System32\wsl.exe ./FBuild-Linux Game-x64-Debug

FBuildWorker.exe Detailed

-console

Disable worker UI.

The FBuildWorker can run in a UI-less mode on Windows. (On OSX and Linux, the worker currently always runs in UI-less mode)

-cpus=[n|-n|n%]

Control worker CPUs allocation.

The number of workers available is normally controlled through the UI of the FBuildWorker.exe. The "-cpus" command line option will override this as follows:

SyntaxDescription
-cpus=nValue n will be used.
-cpus=-nValue of NUMBER_OF_PROCESSORS-n will be used.
-cpus=n%Specify number of CPUs as a percentage of NUMBER_OF_PROCESSORS.

In all cases, the number used will be clamped between 1 and the NUMBER_OF_PROCESSORS environment variable.

NOTE: The newly overridden options will be saved and used on subsequent restarts of the worker.

-debug

[Windows Only] Display a message box on startup to allow a debugger to be attached. Can be useful if triaging problems with FASTBuild that can't be reproduced in the debugger.

-minfreememory

[Windows Only] Override the default minimum memory limit (in MiB) from the default of 1024 (1 GiB). When a worked has less memory available than this amount it will not accept work.

minfreememory
-mode=[disabled|idle|dedicated|proportional]

Control worker availability.

The FBuildWorker.exe mode is normally controlled through the UI. The "-mode" command line option will override this as follows:

SyntaxDescription
-mode=disabledWorker will accept no tasks.
-mode=idleWorker will accept tasks when PC is considered idle.
-mode=dedicatedWorker will accept tasks regardless of PC state.
-mode=proportionalWorker will accept tasks proportional to PC's idle CPU power.

NOTE: The newly overridden options will be saved and used on subsequent restarts of the worker.

-nosubprocess

Don't spawn a sub-process copy of the worker.

By default, when the FBuildWorker is launched, it makes a copy of itself (FBuildWorker.exe.copy), launches the copy and terminates. The duplicate process monitors the original executable file for changes, and re-launches itself if the file is updated. In this way, the FBuildWorker.exe can be kept under revision control, and when synchronized to a new version, will automatically re-start.

The "-nosubprocess" option suppresses this behaviour.

-periodicrestart

Restart worker every 4 hours.

If worker reliability issues are encountered, perhaps due to uncontrolable factors such as OS instability, network driver issues or as yet unresolved FASTBuild bugs, the worker can be instructed to periodically restart itself as a potential workaround.