Contact | License

# 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.
-debug | [Windows Only] Allow attaching a debugger immediately on startup.
-dist | Enable distributed compilation.
-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 | [Experimental] 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 | Output a report at build termination.
-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.

## 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.

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

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

File : Tools/FBuild/FBuildTest/Data/TestCompressor/TestObjFile.o Size : 897329 Compression Decompression Level | Time (ms) MB/s Ratio | Time (ms) MB/s ------------------------------------------------ 0 | 0.232 3682.0 1.00 | 0.023 36863.9 -256 | 0.489 1751.2 1.01 | 0.045 19003.8 -128 | 0.536 1597.5 1.04 | 0.064 13405.2 -64 | 0.722 1184.7 1.13 | 0.113 7542.3 -32 | 0.938 912.4 1.30 | 0.180 4743.1 -16 | 1.197 715.2 1.55 | 0.251 3410.4 -8 | 1.394 614.0 1.85 | 0.268 3194.6 -4 | 1.542 554.9 2.14 | 0.252 3396.2 -2 | 1.563 547.4 2.30 | 0.243 3515.9 -1 | 1.591 538.0 2.40 | 0.240 3563.8 <--- Default 1 | 6.927 123.5 2.85 | 0.247 3466.7 3 | 7.362 116.2 2.91 | 0.253 3379.4 6 | 12.173 70.3 2.96 | 0.311 2753.1 9 | 18.928 45.2 2.97 | 0.308 2774.5 12 | 48.765 17.5 2.98 | 0.299 2858.4
-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.

-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.

-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:

- -noprogress
- -fixuperrorpaths (Windows only)
- -wrapper (Windows only)

-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

[Experimental] Individually build all files normally in Unity.

NOTE: When alternating between specifying -nounity and not, libraries may not relink when they should. The resulting executables are valid, but may contain the previous unity objects instead of the loose objects

-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

Output a detailed report at the end of the build. The report is written to report.html 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:

Syntax | Description
--- | ---
-cpus=n | Value n will be used.
-cpus=-n | Value 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:

Syntax | Description
--- | ---
-mode=disabled | Worker will accept no tasks.
-mode=idle | Worker will accept tasks when PC is considered idle.
-mode=dedicated | Worker will accept tasks regardless of PC state.
-mode=proportional | Worker 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.