Describes a compiler and specifies how to interact with the compiler process for dependency tracking, distribution, caching and more.
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:
.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.
.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:
|auto||(default) Auto detect compiler based on executable path|
|msvc||Microsoft and compatible compilers|
|clang||Clang and compatible compilers|
|gcc||GCC and compatible compilers|
|snc||SNC and compatible compilers|
|codewarrior-wii||CodeWarrior compiler for the Wii|
|greenhills-wiiu||GreenHills compiler for the Wii U|
|cuda-nvcc||NVIDIA's CUDA compiler|
|qt-rcc||Qt's resource compiler|
|orbis-wave-psslc||orbis wave psslc shader compiler|
|custom||Any 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.
.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 exmaple 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 desireable, it can be disabled by setting .ClangRewriteIncludes to false as follows:
.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 undesireable, the .VS2012EnumBugFix option can be enabled to work around the problem at build time.
When the bug occurs, the following code:
This bug can be avoided by inserting additional whitespace into the enum declaration as follows:
.Environment - String or ArrayOfStrings - (Optional)
When set, overrides the environment for local compiles
This allows you to have a different environment per compiler
.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 know 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.