Command Line Options

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.

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

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

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

Example:

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.

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.

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.

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

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)

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.

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.

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.

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.

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)

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.

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.

Individually build all files normally in Unity.

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

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.

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.

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

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.

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.

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.

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

Example:

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.

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

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

Displays a summary upon build completion.

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

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

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

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.

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

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.

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:

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)

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:

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.

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

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

Control worker availability.

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

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

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.

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.