Details of the FASTBuild configuration file syntax can be grouped into 4 categories:
Formatting Directives Variables FunctionsNOTE: This syntax is very simple and will be expanded in the future.
The #if / #endif directive pair allows parts of a bff configuration file to be applied conditionally. The following pre-defined symbols can be used:
Symbol | Value |
---|---|
__LINUX__ | 0 or 1 if running on Windows |
__OSX__ | 0 or 1 if running on OSX |
__WINDOWS__ | 0 or 1 if running on Linux |
The #include directive allows a bff configuration file to include another. This allows the configuration to be split along logical lines, such as per-platform or per-configuration.
Examples:The #once directive specifies that a bff file should only be parsed once, regardless of how many times it is included.
Examples:Variable declarations begin with a period followed by a contiguous block of alphanumeric characters. Variable names are case insensitive. Four variable types are supported (String, Integer, Boolean and Array). Variable types are implied by their declaration.
Examples:Variables can be overridden or modified at any point after they have been declared, as follows:
Variables can be constructed from other variables:
Variables are valid for the scope they are declared in, and all sub-scopes. Modifications to variables within a scope exist only in the scope they are made. For example:
Structs allow the grouping of variables to allow reuse of settings in complex build configurations. Structs contain any number of variables of any type (including other structs). Arrays of structs are also permitted.
A struct contains a number of properties, isolating them from the current namespace. The Using function allows all the members of a struct to be pushed into the current scope:
The Using function also allows Structs to effectively inherit and override other structs.
Looping through arrays of structures is a useful technique for minimizing configuration complexity.
NOTE: See the Function Reference for a detailed list of all available functions and their Arguments and Properties.
Functions describe the dependency information to FASTBuild. Each library, executable, unit test or other "node" is described to FASTBuild through the use of Functions.
Functions generally take the form:
Functions are primarily controlled by their Properties, taken from active variable declarations (either internally declared or from an inherited scope). The recognized properties vary from function to function.
The result of the following two examples are equivalent:
Variables interact with Function properties in this way to allow common declarations to be moved to higher level scope to avoid duplication. Combined with the variable scoping rules, this also allows for bespoke specializations.
Arguments are often optional, and their quantity and syntax varies from function to function. Where they are not required (or optional), brackets should be omitted.
As an example, the Library function takes an optional alias argument to allow a user-friendly name when targetting the library to be built on the command line:
Build-Time Substitutions allow FASTBuild to replace certain configuration values at build time, as opposed to configuration parsing time ($ tokens). This functionality is used whenever the value of an argument can't be known at configuration time, or there is a many to one relationship between the configuration and the number of nodes it results in during the build.
One common example of where build time substitutions are required is when building a library. Since the compiler is invoked for each file, but we only define one set of 'CompilerOptions', a build-time substitution is required. For example:
Assuming there are 3 files in the 'Code' directory ('a.cpp', 'b.cpp' and 'c.cpp'), the compiler will be invoked 3 times. In each case %1 and %2 will be replaced with appropriate values for the input and output. In this case, that means 'a.cpp' & 'Tmp\a.obj' for the first invocation, 'b.cpp' & 'Tmp\b.obj' for the second, and finally 'c.cpp' & 'Tmp\c.obj'.
The behaviour of build-time substitutions is different for each Function (what values they provide and what properties they can be used on). For details, see the Function Reference.