FASTBuild

https://www.fastbuild.org/docs/
Admin
FASTBuild is a high-performance, open-source build system for Windows, Linux, and OS X that supports...
Tokens:108,452
Snippets:1,135
Trust Score:8.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### ProjectBuildCommand example

Source: https://www.fastbuild.org/docs/functions/vcxproject.html

Sets the command to launch when 'build project' is selected.

```FASTBuild
.ProjectBuildCommand = 'fbuild -ide -dist -cache MyProject-X64-Debug'
```

--------------------------------

### ProjectRebuildCommand example

Source: https://www.fastbuild.org/docs/functions/vcxproject.html

Sets the command to launch when 'rebuild project' is selected.

```FASTBuild
.ProjectRebuildCommand = 'fbuild -ide -clean -dist -cache MyProject-X64-Debug'
```

--------------------------------

### .PreBuildDependencies example

Source: https://www.fastbuild.org/docs/functions/copy.html

Shows how to use .PreBuildDependencies to ensure a target is built before copying generated files.

```fastbuild
.Source = { 'generated/scripts/program.exe' 'generated/scripts/program.pdb' }
.Dest = 'bin/'
.PreBuildDependencies = 'Compile' // Make sure exe completes (so pdb is written before copy)
// (assuming this is a previously defined target)
```

--------------------------------

### .Source option examples

Source: https://www.fastbuild.org/docs/functions/copy.html

Shows how to set .Source to a single file or an array of files.

```fastbuild
.Source = 'folder/file.ext'
```

```fastbuild
.Source = { 'folder/file.a', 'folder/file.b' }
```

--------------------------------

### Source directory structure example

Source: https://www.fastbuild.org/docs/functions/copydir.html

Shows the source directory structure used in the CopyDir example. The folder contains a file and a subdirectory with another file.

```plaintext
folder\filea.dat
folder\subdir\fileb.dat
```

--------------------------------

### .Dest option examples

Source: https://www.fastbuild.org/docs/functions/copy.html

Shows how to set .Dest to a directory or a filename for renaming.

```fastbuild
.Dest = 'out/'
```

```fastbuild
.Dest = 'out/renamedFile.ext'
```

--------------------------------

### #include example: splitting configuration

Source: https://www.fastbuild.org/docs/syntaxguide.html

Includes multiple .bff files to split configuration along logical lines.

```bff
#include "platforms/x86.bff"
#include "platforms/x64.bff"
#include "libs/core.bff"
#include "libs/graphics.bff"
#include "libs/sound.bff"
#include "game.bff"
```

--------------------------------

### FASTBuild cyclic dependency error #1043 example and fix

Source: https://www.fastbuild.org/docs/errors/1043.html

Shows a cyclic dependency example where .ExecInput and .ExecOutput are the same file, the resulting FASTBuild error #1043, and the corrected configuration with different input and output files.

```FASTBuild
Exec( 'bad' ) {
    .ExecExecutable = 'dostuff.exe'
    .ExecInput = 'file.txt'
    .ExecOutput = 'file.txt' // Cyclic dependency
}
```

```plaintext
c:\Test\fbuild.bff(5,1): FASTBuild Error #1043 - Cyclic dependency detected for node 'C:\Test\file.txt'.
Exec( 'bad' )
^
\--here
```

```FASTBuild
Exec( 'good' ) {
    .ExecExecutable = 'dostuff.exe'
    .ExecInput = 'file.txt'
    .ExecOutput = 'output.txt'
}
```

--------------------------------

### ProjectImport example

Source: https://www.fastbuild.org/docs/functions/vcxproject.html

Shows how to define a single .ProjectImport struct and assign it to .ProjectProjectImports.

```FASTBuild
.ProjectImport = [
    .Condition = "'^$(ConfigurationType)' == 'Makefile'"
    .Project = "^$(VCTargetsPath)\Platforms\^$(Platform)\Custom.Makefile.targets"
]
.ProjectProjectImports = { .ProjectImport }
```

--------------------------------

### Example with Debug and Release configurations

Source: https://www.fastbuild.org/docs/functions/vcxproject.html

Defines two project configurations (Debug and Release) for the Win32 platform and assigns them to .ProjectConfigs.

```FASTBuild
.DebugConfig = [
    .Platform = 'Win32'
    .Config = 'Debug'
]
.ReleaseConfig = [
    .Platform = 'Win32'
    .Config = 'Release'
]
.ProjectConfigs = { .DebugConfig, .ReleaseConfig }
```

--------------------------------

### Example configuration with missing include

Source: https://www.fastbuild.org/docs/errors/1032.html

Configuration that triggers error 1032 because the include file 'missing.bff' cannot be opened.

```plaintext
#include "missing.bff"
```

--------------------------------

### .SourceBasePath example with output structure

Source: https://www.fastbuild.org/docs/functions/copy.html

Shows how .SourceBasePath replicates the sub-directory structure relative to the base path, and the resulting output structure.

```fastbuild
.Source = { 'in/folderA/fileA.ext' 'in/folderA/subDir/fileB.ext' }
.SourceBasePath = 'in/'
.Dest = 'out/'
```

```text
out/folderA/fileA.ext
out/folderA/subDir/fileB.ext
```

--------------------------------

### Build Target by Output Path with fbuild

Source: https://www.fastbuild.org/docs/quickstartguide.html

Build a target by specifying its output file path on the fbuild command line. This example builds Out\LibA\LibA.lib.

```text
c:\p4\Code>fbuild Out\LibA\LibA.lib
```

--------------------------------

### Config: Alias( 'name' ) {

Source: https://www.fastbuild.org/docs/errors/1025.html

Example configuration that triggers error #1025 because the closing '}' token is missing.

```plaintext
Alias( 'name' ) {
```

--------------------------------

### #import example: VS120COMNTOOLS

Source: https://www.fastbuild.org/docs/syntaxguide.html

Imports an environment variable and uses it in a compiler path. The variable is created at the scope of the #import.

```bff
#import VS120COMNTOOLS
.VisualStudio2012Compiler = '$VS120COMNTOOLS$\\..\\..\VC\bin\cl.exe'
```

--------------------------------

### Build Target by Alias with fbuild

Source: https://www.fastbuild.org/docs/quickstartguide.html

Build a target using its alias, which is created by the Library function. This example builds libA, which is equivalent to building Out\LibA\LibA.lib.

```text
c:\p4\Code>fbuild libA
```

--------------------------------

### FASTBuild #if expression cannot start with boolean operator

Source: https://www.fastbuild.org/docs/errors/1046.html

The first example shows an invalid #if expression that starts with a boolean operator, causing FASTBuild error #1046. The second is the compiler output showing the error location. The third is the corrected expression with the boolean operator between defines.

```text
#if &&AAA #endif
```

```text
c:\test\fbuild.bff(1,5): FASTBuild Error #1046 - #if expression cannot start with boolean operator. #if &&AAA ^ \--here
```

```text
#if AAA && BBB #endif
```

--------------------------------

### #define / #undef example: conditional token definition

Source: https://www.fastbuild.org/docs/syntaxguide.html

Shows how to define and undefine tokens to control BFF flow. The first example defines ENABLE_PDB_STORING on Windows; the second undefines USE_CLANG_COMPILER on Windows.

```bff
#if __WINDOWS__
#define ENABLE_PDB_STORING
#endif
#if ENABLE_PDB_STORING
...
```

```bff
#define USE_CLANG_COMPILER
#if __WINDOWS__
#undef USE_CLANG_COMPILER
#endif
#if USE_CLANG_COMPILER
...
```

--------------------------------

### Example: Modifying frozen variable in ForEach

Source: https://www.fastbuild.org/docs/errors/1060.html

This example triggers error #1060 by attempting to modify the array being iterated. The variable .Array is frozen during ForEach, so the assignment ^Array + 'loop variables are frozen' fails.

```FASTBuild
.Array = { 'a', 'b', 'c' }
ForEach( .Item in .Array )
{
    ^Array + 'loop variables are frozen'
}
```

--------------------------------

### BFF example using Print() with ForEach and Using

Source: https://www.fastbuild.org/docs/functions/print.html

A sample BFF that defines configurations and uses ForEach with Using to print the target name for each configuration. The output shows the generated target names.

```bff
.X86_Debug = [ .Config = 'Debug' .Platform = 'X86' ]
.X86_Release = [ .Config = 'Release' .Platform = 'X86' ]
.X64_Debug = [ .Config = 'Debug' .Platform = 'X64' ]
.X64_Release = [ .Config = 'Release' .Platform = 'X64' ]
.Configs = { .X86_Debug, .X86_Release, .X64_Debug, .X64_Release }
ForEach( .Config in .Configs )
{
    Using( .Config )
        .TargetName = '$Platform$-$Config$'
        Print( 'TargetName = $TargetName$' )
}
```

```output
TargetName = X86-Debug
TargetName = X86-Release
TargetName = X64-Debug
TargetName = X64-Release
```

--------------------------------

### #if ! operator example

Source: https://www.fastbuild.org/docs/syntaxguide.html

Inverts an if expression with the ! operator.

```bff
#if !USE_MSVC
#define USE_CLANG
#endif
```

--------------------------------

### file_exists() example

Source: https://www.fastbuild.org/docs/syntaxguide.html

Detects the existence of an external file.

```bff
#if file_exists("file.dat")
//
#endif
```

--------------------------------

### main.cpp - Hello World source

Source: https://www.fastbuild.org/docs/examples/helloworld_windows.html

Simple C++ program that prints 'Hello!' to the console. Used as the input for the FASTBuild configuration.

```cpp
#include "stdio.h"
int main(int, char[]) {
    printf( "Hello!\n" );
    return 0;
}
```

--------------------------------

### ListDependencies

Source: https://www.fastbuild.org/docs/functions/listdependencies.html

Documentation for the ListDependencies function, including its syntax, parameters, details, and an example.

```APIDOC
## ListDependencies

### Description
Creates a text file containing all file dependencies for the given source. This function can be useful to pipe FASTBuild dependency inspection inside another build system.

### Syntax
ListDependencies( alias ) ; (optional) Alias

### Parameters
- **Alias** (optional) - The alias for this function.
- **.Source** - Source target (filename or node name).
- **.Dest** - Destination filename where dependent files list will be exported.
- **.SourcePattern** (optional) - String, or array of strings, to filter exported dependencies.
- **.PreBuildDependencies** (optional) - Force targets to be built before this ListDependencies (Rarely needed).

### Details
- Output file format is simple: one file per line.
- Each dependency is always expressed as an absolute path.
- Results are sorted lexically, by ascending order.
- Output file is using CRLF on Windows, and LF on other platforms.
- List only direct dependencies of the source, **no recursive descent.**

### Example
```
ObjectList( 'SimpleObject' ) {
    .CompilerInputFiles = "C:/Test/SimpleObject.cpp"
    .CompilerOutputPath = "C:/Test/Output"
}
ListDependencies( 'SimpleDependencies' ) {
    .Source = 'SimpleObject'
    .SourcePattern = { '*.h', '*.c', '*.cpp' }
    .Dest = 'C:/Test/Output/Dependencies.txt'
}
```

With 'SimpleObject.cpp' containing:
```
#include "HeaderA.h"
#include "HeaderB.h"
```

Will generate the following 'Dependencies.txt' output file:
```
C:/Test/HeaderA.h
C:/Test/HeaderB.h
C:/Test/SimpleObject.cpp
```
```

--------------------------------

### View preprocessed source with -showcmds and cl.exe /E

Source: https://www.fastbuild.org/docs/troubleshooting/cache.html

First invoke FASTBuild with -showcmds to see the compiler command line, then invoke the preprocessor command line yourself, piping output to a file. Compare results on two machines to find discrepancies. If using LightCache, manually append the preprocessor option (usually /E or -E).

```text
fbuild.exe [target] -cachewrite -showcmds -clean
```

```text
cl.exe someCpp.cpp someObj.obj /E > preprocessed.ii
```

--------------------------------

### Fix for error #1030

Source: https://www.fastbuild.org/docs/errors/1030.html

Intended correction for the #1030 error in the example configuration file.

```unknown
#include "subdir/fbuild.bff"
```

--------------------------------

### Verify FASTBuild Installation with fbuild -version

Source: https://www.fastbuild.org/docs/quickstartguide.html

Run fbuild -version in a command prompt to verify FASTBuild is correctly set up. The output shows the version and platform, e.g., FBuild - v0.98 (x86).

```text
c:\p4\Code>fbuild -version
FBuild - v0.98 (x86)
c:\p4\Code>
```

--------------------------------

### Define custom solution configs with .SolutionConfig and .SolutionPlatform

Source: https://www.fastbuild.org/docs/functions/vssolution.html

Shows how to define custom solution-level configs and platforms when the solution and project configs don't have a 1:1 relationship.

```FASTBuild
.DebugDirectX = [
    .Config = 'Debug-DirectX'
    .Platform = 'Win32'
    .SolutionConfig = 'Debug'
    .SolutionPlatform = 'Win32-DirectX'
]
.DebugOpenGL = [
    .Config = 'Debug-OpenGL'
    .Platform = 'Win32'
    .SolutionConfig = 'Debug'
    .SolutionPlatform = 'Win32-OpenGL'
]
```

--------------------------------

### fbuild.bff - FASTBuild configuration for Windows

Source: https://www.fastbuild.org/docs/examples/helloworld_windows.html

FASTBuild configuration that sets up the Visual Studio 2013 compiler and Windows 7.1A SDK, defines compiler and linker options, and creates an executable target 'HelloWorld' from the source files. It also defines an 'all' alias to build the executable.

```fastbuild
// HelloWorld
//------------------------------------------------------------------------------
// Windows Platform (VS 2013 Compiler, Windows 7.1A SDK)
//------------------------------------------------------------------------------
.VSBasePath = 'C:\Program Files (x86)\Microsoft Visual Studio 12.0'
.WindowsSDKBasePath = 'C:\Program Files (x86)\Microsoft SDKs\Windows\v7.1A'

// Settings
//------------------------------------------------------------------------------
Settings
{
    .Environment = {
        "PATH=$VSBasePath$\Common7\IDE\;$VSBasePath$\VC\bin\",
        "TMP=C:\Windows\Temp",
        "SystemRoot=C:\Windows"
    }
}

// X86 ToolChain
//------------------------------------------------------------------------------
.Compiler = '$VSBasePath$\VC\bin\cl.exe'
.CompilerOptions = '"%1"'          // Input
                + ' /Fo"%2"'       // Output
                + ' /Z7'            // Debug format (in .obj)
                + ' /c'             // Compile only
                + ' /nologo'        // No compiler spam
                + ' /W4'            // Warning level 4
                + ' /WX'            // Warnings as errors

.Linker = '$VSBasePath$\VC\bin\link.exe'
.LinkerOptions = ' /OUT:"%2"'     // Output
               + ' "%1"'           // Input
               + ' /WX'             // Warnings as errors
               + ' /NOLOGO'         // No linker spam
               + ' /DEBUG'          // Keep debug info when linking
               + ' /NODEFAULTLIB'   // We'll specify the libs explicitly

// Include paths
//------------------------------------------------------------------------------
.BaseIncludePaths = ' /I"./"'
                  + ' /I"$VSBasePath$/VC/include/"'
.CompilerOptions + .BaseIncludePaths

// Library paths
//------------------------------------------------------------------------------
.LibPaths = ' /LIBPATH:"$WindowsSDKBasePath$\Lib"'
          + ' /LIBPATH:"$VSBasePath$\VC\lib"'
.LinkerOptions + .LibPaths

// HelloWorld
//------------------------------------------------------------------------------
ObjectList( 'HelloWorld-Lib' )
{
    .CompilerInputPath = '\'
    .CompilerOutputPath = 'Out\'
}

Executable( 'HelloWorld' )
{
    .Libraries = { "HelloWorld-Lib" }
    .LinkerOutput = 'Out\HelloWorld.exe'
    .LinkerOptions + ' libcmt.lib'      // Std Lib (Multi-Threaded, Static, Release)
                   + ' kernel32.lib'    // Kernel functions
}

// All
//------------------------------------------------------------------------------
Alias( 'all' )
{
    .Targets = { 'HelloWorld' }
}
```

--------------------------------

### #once example: preventing multiple parsing

Source: https://www.fastbuild.org/docs/syntaxguide.html

Shows how #once in Common.bff ensures it is parsed only once even when included by multiple files.

```bff
// Common.bff - containing common configuration options
#once
```

```bff
// LibraryA.bff
#include "Common.bff"
```

```bff
// LibraryB.bff
#include "Common.bff"
```

```bff
// fbuild.bff - the root config file
#include "LibraryA.bff"
#include "LibraryB.bff"
```

--------------------------------

### Corrected function call

Source: https://www.fastbuild.org/docs/errors/1110.html

The corrected version of the example, adding the empty parentheses to properly invoke the function.

```plaintext
function Func(){} Func()
```

--------------------------------

### Define .SolutionFolders with projects and items

Source: https://www.fastbuild.org/docs/functions/vssolution.html

Organizes projects and solution items into folders. Folders may contain projects and/or items, or can be empty.

```FASTBuild
.FolderA = [
    .Path = 'Libraries'
    .Projects = { 'LibraryA-proj', 'LibraryB-proj' }
    .Items = { 'rel_path_to/item_file_1.txt', 'rel_path_to/item_file_2.ext' }
]
.FolderB = [
    .Path = 'Executables'
    .Projects = { 'Exe-proj' }
]
.SolutionFolders = {
    .FolderA,
    .FolderB
}
```

--------------------------------

### Valid Built-in Function Fix

Source: https://www.fastbuild.org/docs/errors/1015.html

A valid example using the built-in Alias function to resolve the error.

```plaintext
Alias( 'MyAlias' ) // A valid built-in Function { ... }
```

--------------------------------

### Copy function signature with options

Source: https://www.fastbuild.org/docs/functions/copy.html

Shows the Copy function signature and its available options: .Source, .Dest, .SourceBasePath, and .PreBuildDependencies.

```fastbuild
Copy( name ) // (optional) Alias
{
    // Basic options
    .Source // File(s) to copy
    .Dest // Destination (path or filename)

    // Advanced options
    .SourceBasePath // (optional) Base directory to copy partial relative hierarchy (see below)

    // Additional options
    .PreBuildDependencies // (optional) Force targets to be built before this Copy (Rarely needed,
                          // but useful when Copy relies on externally generated files).
}
```

--------------------------------

### Error output for #1011

Source: https://www.fastbuild.org/docs/errors/1011.html

The compiler output when the bad example is used, showing the error message and location.

```plaintext
c:\Test\fbuild.bff(1):(7) FASTBuild Error #1011 - Unnamed modification must follow a variable assignment in the same scope. + 'String' ^ \--here
```

--------------------------------

### Define .SolutionConfigs with two configurations

Source: https://www.fastbuild.org/docs/functions/vssolution.html

Defines solution configurations for Debug and Release on the Win32 platform. If not specified, a default matrix of Win32|Debug, Win32|Release, x64|Debug, and x64|Release is used.

```FASTBuild
.Solution_Config_Debug = [
    .Platform = 'Win32'
    .Config = 'Debug'
]
.Solution_Config_Release = [
    .Platform = 'Win32'
    .Config = 'Release'
]
.SolutionConfigs = {
    .Solution_Config_Debug,
    .Solution_Config_Release
}
```

--------------------------------

### #if / #elif / #else / #endif example: compiler selection

Source: https://www.fastbuild.org/docs/syntaxguide.html

Conditionally applies configuration based on defined tokens. Supports && and || with C precedence; no parentheses. The #else branch causes an error if no compiler is specified.

```bff
#if USE_MSVC
.CompilerOptions = '/c "%1" /Fo"%2"'
#elif USE_CLANG
.CompilerOptions = '-c "%1" -o "%2"'
#else
No compiler specified // Cause an error
#endif
```
Tokens:
Raw