Compiler

Summary

Describes a compiler and specifies how to interact with the compiler process for dependency tracking, distribution, caching and more.

Compiler( 'name' ) // Alias { .Executable // Primary compiler executable .ExtraFiles // (optional) Additional files (usually dlls) required by the compiler. // Additional Options .CompilerFamily // (optional) Explicitly specify compiler type (default: auto) .AllowDistribution // (optional) Allow distributed compilation (if available) (default: true) .ExecutableRootPath // (optional) Override default path for executable distribution .SimpleDistributionMode // (optional) Allow distribution of otherwise unsupported "compilers" (default: false) .CustomEnvironmentVariables // (optional) Environment variables to set on remote host .ClangRewriteIncludes // (optional) Use Clang's -frewrite-includes option when preprocessing (default: true) .ClangGCCUpdateXLanguageArg // (optional) Update -x language arg for second pass of compilation (default: false) .VS2012EnumBugFix // (optional) Enable work-around for bug in VS2012 compiler (default: false) .Environment // (optional) Environment variables to use for local build .AllowResponseFile // (optional) Allow response files to be used if not auto-detected (default: false) .ForceResponseFile // (optional) Force use of response files (default: false) // Temporary Options .UseLightCache_Experimental // (optional) Enable experimental "light" caching mode (default: false) .UseRelativePaths_Experimental// (optional) Enable experimental relative path use (default: false) .SourceMapping_Experimental // (optional) Use Clang's -fdebug-source-map option to remap source files .ClangFixupUnity_Disable // (optional) Disable preprocessor fixup for Unity files (default: false) }
Details

FASTBuild needs to know the location of your compiler executable. The filename of the executable is used to make determinations at runtime about how FASTBuild interacts with the compiler.

For distributed compilation, FASTBuild additionally needs to know the list of additional files that need to be synchronized to the remote machine.

A compiler can be declared as follows:

Compiler( 'Compiler-Clang-Windows' ) { .Executable = '$ClangForWindowsBasePath$\clang++.exe' }
A declared compiler can then be referenced by an ObjectList or Library:
Library( 'libA' ) { .Compiler = 'Compiler-Clang-Windows' // Other options as normal...

Basic Options

.Executable - String - (Required)

The primary compiler executable that will be invoked by FASTBuild when this Compiler() is used.


.ExtraFiles - String/ArrayOfStrings - (Optional)

For distributed compilation, the specified files will also be synchronized to the remote machine. The relative location of the source files controls how they will be mirrored on the remote machine. Files in 'ExtraFiles' in the same directory or in sub-directories under the primary 'Executable' will be placed in the same relative location on the remote machine. 'ExtraFiles' in other folders will be placed at the same level as the executable.

// Path behaviour example Compiler( 'Test' ) { .Executable = 'C:\compiler\compiler.exe' // dest: compiler.exe .ExtraFiles = { 'C:\compiler\subdir\helper.dll' // dest: subdir/helper.exe 'C:\cruntime\mvscrt.dll' // dest: msvcrt.dll }

Additional Options

.CompilerFamily - String - (Optional)

By default, FASTBuild will detect the compiler type based on the executable name. The .CompilerFamily property allows you to explicitly control the compiler type instead. This can be useful for:

  • custom variants of compilers with unique naming
  • custom exeutables used as compilers

The following values are supported:

ValueNotes
auto(default) Auto detect compiler based on executable path
 
ValueNotes
msvcMicrosoft and compatible compilers
clangClang and compatible compilers
clang-clClang in MSVC cl-compatible mode
gccGCC and compatible compilers
sncSNC and compatible compilers
codewarrior-wiiCodeWarrior compiler for the Wii
greenhills-wiiuGreenHills compiler for the Wii U
cuda-nvccNVIDIA's CUDA compiler
qt-rccQt's resource compiler
vbccvbcc compiler
orbis-wave-psslcorbis wave psslc shader compiler
csharpC# compiler
 
ValueNotes
customAny custom compiler. NOTE: Only primary input and output dependencies will be tracked. No additional dependencies will be tracked as FASTBuild has no way to extract dependency information from arbitrary executables.


.AllowDistribution - Boolean - (Optional)

For compilers where distributed compilation is supported, said feature can be disabled.


.ExecutableRootPath - String - (Optional)

When a compiler is distributed the .Compiler and .ExtraFiles hierarchy is replicated on the remote machine as documented above (see .ExtraFiles). The base path for this replication can be overriden by setting the .ExectuableRootPath property, allowing more flexibility in how the file hierarchy is replicated on the remote host.


.SimpleDistributionMode - Boolean - (Optional)

FASTbuild supports distributed compilation for certain compilers that it explicitly understands how to interact with in order to obtain dependency information (in addition to the simple primary input file). By setting .SimpleDistributionMode, FASTBuild can be told that the single file input of a "compiler" is the only dependency and thus can be safely used with distributed compilation. This allows distribution of custom tools or other useful work like texture conversion.


.CustomEnvironmentVariables - String or ArrayOfStrings - (Optional)

When compiling on a remote host, a clean environment is used. If needed, environment variables can be set.


.AllowResponseFile - Boolean - (Optional)

Allow the use of Response Files for passing arguments to the compiler when they exceed operating system limits.

FASTBuild automatically detects that some compilers can use Response Files and uses them accordingly. For situations that FASTBuild doesn't auto-detect (such as custom compilers), AllowResponseFile can be set manually.


.ForceResponseFile - Boolean - (Optional)

Force the use of Response Files for passing arguments to the compiler.

FASTBuild uses Response Files to pass command line arguments to Compilers that support them only when needed (length exceeds operating system limits). This is to limit the overhead of Response File creation to situations that require it.

Use of Response Files in all cases can be forced with .ForceResponseFile if required.


.ClangRewriteIncludes - Bool - (Optional)

FASTBuild uses the -E preprocessor option when compiling with Clang to preprocess the source code. In order to improve consistency between this preprocessed source and the original source, FASTBuild also uses the -frewrite-includes option by default. An example of this improved consistency is that compiler errors originating from macros will have the caret point to the correct column location of the source code instead of the column location where the error would be in the expanded macro.

If for some reason the use of -frewrite-includes is not desirable, it can be disabled by setting .ClangRewriteIncludes to false as follows:

.ClangRewriteIncludes = false


.ClangGCCUpdateXLanguageArg - Bool - (Optional)

FASTBuild uses the -E preprocessor option combined with -frewrite-includes when preprocessing source with Clang to preserve debug information. If the -x language arg is specified explicitly by the user on the command line (for example "-x c++"), this is only correct for the first pass.

FASTBuild can update this arg ("-x c++" -> "-x c++-cpp-output" for example) but older versions of Clang (prior to 10) will ignore define (-D) options on the command line when this is set, breaking compilation when -frewrite-includes is used).

To maintain backwards compatibility, this option is disabled by default and must be explicitly enabled if desired.


.VS2012EnumBugFix - Bool - (Optional)

NOTE: This option incurs a minor build time cost that impacts compile times.

A bug exists in the Visual Studio 2012 compiler whereby enums in preprocessed code are sometimes incorrectly processed when they lie on specific buffer alignment boundaries. This bug is fixed in Visual Studio 2013 and later.

If a manual work around (described below) is impractical or undesirable, the .VS2012EnumBugFix option can be enabled to work around the problem at build time.

When the bug occurs, the following code:

enum dateorder { no_order, dmy, mdy, ymd, ydm };
May be incorrectly pre-processed as:
enummdateorder { no_order, dmy, mdy, ymd, ydm };
This results in very unintuitive compile errors.

This bug can be avoided by inserting additional whitespace into the enum declaration as follows:

enum dateorder { no_order, dmy, mdy, ymd, ydm };
This work-around may be impractical if a large number of enums are affected, or if the enum(s) originate in system headers or external code. In those cases the .VS2012EnumBugFix option can be enabled to insert the additional whitespace at build-time.


.Environment - String or ArrayOfStrings - (Optional)

When set, overrides the environment for local compiles

This allows you to have a different environment per compiler

Examples
MSVC - 2019 (v16.8.3)
// VisualStudio 2019 x64 Compiler .VS2019_BasePath = 'C:\Program Files (x86)\Microsoft Visual Studio\2019\2019\Community' .VS2019_Version = '14.28.29333' Compiler( 'Compiler-VS2019-x64' ) { .Root = '$VS2019_BasePath$/VC/Tools/MSVC/$VS2019_Version$/bin/Hostx64/x64' .Executable = '$Root$/cl.exe' .ExtraFiles = { '$Root$/c1.dll' '$Root$/c1xx.dll', '$Root$/c2.dll', '$Root$/atlprov.dll', // Only needed if using ATL '$Root$/msobj140.dll' '$Root$/mspdb140.dll' '$Root$/mspdbcore.dll' '$Root$/mspdbsrv.exe' '$Root$/mspft140.dll' '$Root$/msvcp140.dll' '$Root$/msvcp140_atomic_wait.dll' // Required circa 16.8.3 (14.28.29333) '$Root$/tbbmalloc.dll' // Required as of 16.2 (14.22.27905) '$Root$/vcruntime140.dll' '$Root$/vcruntime140_1.dll' // Required as of 16.5.1 (14.25.28610) '$Root$/1033/clui.dll' '$Root$/1033/mspft140ui.dll' // Localized messages for static analysis } }
MSVC - 2017
// VisualStudio 2017 x64 Compiler .VS2017_BasePath = 'C:\Program Files (x86)\Microsoft Visual Studio\2017\2017\Community' .VS2017_Version = '14.16.27023' Compiler( 'Compiler-VS2017-x64' ) { .Root = '$VS2017_BasePath$\VC\Tools\MSVC\$VS2017_Version$\bin\Hostx64\x64' .Executable = '$Root$\cl.exe' .ExtraFiles = { '$Root$\c1.dll' '$Root$\c1xx.dll', '$Root$\c2.dll', '$Root$\atlprov.dll', // Only needed if using ATL '$Root$\msobj140.dll' '$Root$\mspdb140.dll' '$Root$\mspdbcore.dll' '$Root$\mspdbsrv.exe' '$Root$\mspft140.dll' '$Root$\msvcp140.dll' '$Root$\vcruntime140.dll' '$Root$\1033/clui.dll' } }
MSVC - 2013
// VisualStudio 2013 x86 Compiler Compiler( 'Compiler-x86' ) { .Executable = '$VSBasePath$\VC\bin\cl.exe' .ExtraFiles = { '$VSBasePath$\VC\bin\c1.dll' '$VSBasePath$\VC\bin\c1ast.dll', '$VSBasePath$\VC\bin\c1xx.dll', '$VSBasePath$\VC\bin\c1xxast.dll', '$VSBasePath$\VC\bin\c2.dll', '$VSBasePath$\VC\bin\atlprov.dll', // Only needed if using ATL '$VSBasePath$\VC\bin\msobj120.dll' '$VSBasePath$\VC\bin\mspdb120.dll' '$VSBasePath$\VC\bin\mspdbcore.dll' '$VSBasePath$\VC\bin\mspft120.dll' '$VSBasePath$\VC\bin\1033\clui.dll' '$VSBasePath$\VC\redist\x86\Microsoft.VC120.CRT\msvcp120.dll' '$VSBasePath$\VC\redist\x86\Microsoft.VC120.CRT\msvcr120.dll' '$VSBasePath$\VC\redist\x86\Microsoft.VC120.CRT\vccorlib120.dll' } }
Clang
// Clang for Windows Compiler( 'Compiler-x86Clang' ) { .Executable = '$ClangForWindowsBasePath$\clang++.exe' }
Intel
// Intel 2015 Update 4 x64 Compiler Compiler( 'Compiler-x64Intel' ) { .Executable = '$IntelBasePath$\bin\intel64\icl.exe' .ExtraFiles = { // DLLs required by icl.exe '$IntelBasePath$\bin\intel64\FNP_Act_Installer.dll' '$IntelBasePath$\bin\intel64\IntelRemoteMon.dll' // EXEs used by icl.exe '$IntelBasePath$\bin\intel64\mcpcom.exe' // License file 'C:\Program Files (x86)\Common Files\Intel\Licenses\XXXXXXXXXX.lic' // NOTE: Your license file // Intel compiler depends on the Microsoft compiler '$VSBasePath$\VC\bin\amd64\cl.exe' '$VSBasePath$\VC\bin\amd64\c1.dll' '$VSBasePath$\VC\bin\amd64\c1ast.dll', '$VSBasePath$\VC\bin\amd64\c1xx.dll', '$VSBasePath$\VC\bin\amd64\c1xxast.dll', '$VSBasePath$\VC\bin\amd64\c2.dll', '$VSBasePath$\VC\bin\amd64\msobj120.dll' '$VSBasePath$\VC\bin\amd64\mspdb120.dll' '$VSBasePath$\VC\bin\amd64\mspdbsrv.exe' '$VSBasePath$\VC\bin\amd64\mspdbcore.dll' '$VSBasePath$\VC\bin\amd64\mspft120.dll' '$VSBasePath$\VC\bin\amd64\1033\clui.dll' '$VSBasePath$\VC\redist\x64\Microsoft.VC120.CRT\msvcp120.dll' '$VSBasePath$\VC\redist\x64\Microsoft.VC120.CRT\msvcr120.dll' '$VSBasePath$\VC\redist\x64\Microsoft.VC120.CRT\vccorlib120.dll' } }
Temporary Options

.UseLightCache_Experimental - Boolean - (Optional)

When set, activates "Light Caching" mode. Light Caching mode avoids using the compiler's preprocessor for cache lookups, instead allowing FASTBuild to parse the files itself to gather the required information. This parsing is significantly faster than for each file and additionally allows FASTBuild to eliminate redundant file parsing between object files, further accelerating cache lookups.

NOTE: This feature should be used with caution. While there are no known issues (it self disables when known to not work - see other notes) it should be considered experimental.

NOTE: For now, Light Caching can only be used with the MSVC compiler. Support will be extended to other compilers in future versions.

NOTE: Light Caching does not support macros using for include paths (i.e. "#include MY_INCLUDE_HEADER") Support for this will be added in future versions.


.UseRelativePaths_Experimental - Boolean - (Optional)

Use relative paths where possible. This is an experiment to lay a possible foundation for path-independent caching.

NOTE: This feature is incomplete and should not be used.


.SourceMapping_Experimental - String - (Optional)

Provides a new root to remap source file paths to so they are recorded in the debugging information as if they were stored under the new root. For example, if $_WORKING_DIR_$ is "/path/to/original", a source file "src/main.cpp" would normally be recorded as being stored under "/path/to/original/src/main.cpp", but with .SourceMapping_Experimental='/another/root' it would be recorded as "/another/root/src/main.cpp" instead.

While the same effect could be achieved by passing "-fdebug-prefix-map=$_WORKING_DIR_$=/another/root" to the compiler via .CompilerOptions, doing so prevents caching from working across machines that use different root paths because the cache keys would not match.

Source mapping can help make builds more reproducible, and also improve the debugging experience by making it easier for the debugger to find source files when debugging a binary built on another machine. See the GCC documentation for -fdebug-prefix-map for more information.

NOTE: This feature currently only works on Clang 3.8+ and GCC.

NOTE: Paths expanded from the __FILE__ macro are not remapped because that requires Clang 10+ and GCC 8+ (-fmacro-debug-map).

NOTE: Only one mapping can be provided, and the source directory for the mapping is always $_WORKING_DIR_$.

NOTE: This option currently inhibits dsitributed compilation. This will be resolved in a future release.


.ClangFixupUnity_Disable - Boolean - (Optional)

Disable preprocessor fixup for Unity files (default: false).

When compiling Unity files with Clang, FASTBuild will modify the preprocessed output so that the files included by the Unity are considered to be the top level file(s), instead of the Unity file. This makes Clang's warning behavior (particularly for static analysis) consistent between Unity and non-Unity compilation.

This temporary option disables this behavior and is provided as a safety mechanism in case there are unforeseen problems with this feature. This toggle is expected to be removed in v1.01.