FASTBuild - Function Reference

Generates a project file for use with Visual Studio, allowing integration of FASTBuild into Visual Studio solutions.

VCXProject( alias ) // (optional) Alias { // Output Options .ProjectOutput // Filename of project file // Input Options .ProjectInputPaths // (optional) Paths to include in project .ProjectInputPathsExclude // (optional) Paths to exclude from project .ProjectInputPathsRecurse // (optional) Recurse into project input paths when finding files (default true) .ProjectPatternToExclude // (optional) Pattern(s) for files to exclude from project .ProjectAllowedFileExtensions // (optional) Extensions to allow in path searches .ProjectFiles // (optional) List of files to include in project .ProjectFilesToExclude // (optional) List of files to exclude from project .ProjectBasePath // (optional) Base path(s) for root folder(s) in project .ProjectFileTypes // (optional) List of filters to override base file types (see below) // Build Config Options .ProjectConfigs // (optional) List of project configurations, see below for details. // (default: Debug Win32, Release Win32, Debug X64, Release X64) // Reference Options .ProjectReferences // (optional) References to assemblies (e.g "System.Core") .ProjectProjectReferences // (optional) References to projects (e.g. "myproj.csproj|{guid}") // Project Import Options .ProjectProjectImports // (optional) Array of ProjectImports, see below for details // Other Options .ProjectGuid // (optional) Override default generated ProjectGuid .DefaultLanguage // (optional) Default Language Property (for XboxOne/WinRT) .ApplicationEnvironment // (optional) Application Environment (for XboxOne/WinRT) .ProjectSccEntrySAK // (optional) Project will contain source control binding strings // Additional configuration options - see below } // ProjectFileTypes - structs in the following format //--------------------------------------------------- .ProjectFileType = [ .FileType // FileType to use (e.g. "CppForm") .Pattern // Pattern of files to apply to (e.g. "*\\Forms\\*.h") ] // ProjectProjectImports - structs in the following format //------------------------------------------------- .ProjectImport = [ .Condition // Condition for import .Project // Path to file to import ] // ProjectConfigs - structs in the following format //------------------------------------------------- .ProjectConfig = [ .Platform // Platform (e.g. Win32, X64, PS3 etc.) .Config // Config (e.g. Debug, Release etc.) .Target // (optional) Previously defined Build Target // Additional configuration options - see below ] // Additional Configuration options //--------------------------------- // Compilation (optional) .ProjectBuildCommand // (optional) Command to launch when "build project" is selected. .ProjectRebuildCommand // (optional) Command to launch when "rebuild project" is selected. .ProjectCleanCommand // (optional) Command to launch when "clean project" is selected. // Compilation Input/Output (optional) .Output // (optional) Output generated by compilation. .OutputDirectory // (optional) Output directory for Visual Studio. .IntermediateDirectory // (optional) Intermediate directory for Visual Studio. .BuildLogFile // (optional) Build log file for Visual Studio. .LayoutDir // (optional) Directory to prepare Layout (for XboxOne). .LayoutExtensionFilter // (optional) Files to filter from Layout (for XboxOne). // Intellisense Options (optional) .PreprocessorDefinitions // (optional) Preprocessor definitions. .IncludeSearchPath // (optional) Include search paths. .ForcedIncludes // (optional) Force included files. .AssemblySearchPath // (optional) Assembly search paths. .ForcedUsingAssemblies // (optional) Forced Using assemblies. .AdditionalOptions // (optional) Additional compiler options. // Debugging Options (optional) .LocalDebuggerCommand // (optional) Executable to launch when debugging. .LocalDebuggerCommandArguments // (optional) Args passed to executable when debugging. .LocalDebuggerWorkingDirectory // (optional) Working Dir for executable when debugging. .LocalDebuggerEnvironment // (optional) Environment variables when debugging. .RemoteDebuggerCommand // (optional) Executable to launch when debugging remotely. .RemoteDebuggerCommandArguments // (optional) Args passed to remote executable when debugging. .RemoteDebuggerWorkingDirectory // (optional) Working Dir for remote executable when debugging. .Xbox360DebuggerCommand // (optional) Debugger command for Xbox360 only. .DebuggerFlavor // (optional) Debugger flavor. .AumidOverride // (optional) Aumid override (for XboxOne). .Keyword, // (optional) Keyword .ApplicationType, // (optional) Application type .ApplicationTypeRevision, // (optional) Application type revision .TargetLinuxPlatform // (optional) Set the Linux platform type .LinuxProjectType // (optional) Set the project type GUID for Linux .PackagePath, // (optional) Path to package to debug .AdditionalSymbolSearchPaths, // (optional) Additional symbol search paths for debugging .AndroidApkLocation // (optional) Location of APK for Android Game Development Extension .AndroidDebugComponent // (optional) Debug component for Android Game Development Extension .AndroidDebugTarget // (optional) Debug target for Android Game Development Extension .AndroidJdb // (optional) JDB for Android Game Development Extension .AndroidLldbPostAttachCommands // (optional) LLDB post attach cmds for Android Game Development Extension .AndroidLldbStartupCommands // (optional) LLDB startup cmds for Android Game Development Extension .AndroidPostApkInstallCommands // (optional) Post APK install cmds for Android Game Development Extension .AndroidPreApkInstallCommands // (optional) Pre APK install cmds for Android Game Development Extension .AndroidSymbolDirectories // (optional) Symbol dirs for Android Game Development Extension .AndroidWaitForDebugger // (optional) Wait for Debugger for Android Game Development Extension .LaunchFlags // (optional) Launch flags for Android Game Development Extension // Misc .PlatformToolset // (optional) Specify PlatformToolset. .DeploymentType // (optional) Specify deployment type for Xbox360. .DeploymentFiles // (optional) Specify files to add to deployment for Xbox360. .RootNamespace // (optional) Set RootNamespace for project

VCXProject generates a Visual Studio project file for use with VSSolution. Generated projects are compatible with VS 2010 and later.

.ProjectOutput - String - (Required)

The output location of the .vcxproj file.

Example:

.ProjectOutput = 'tmp/VisualStudio/Library/Library.vcxproj'

Files which will be included in the generated project can be specified in several ways. Files included in/excluded from the project do not impact compilation (which is still entirely controlled by the rules configured within the BFF file).

.ProjectInputPaths - String or ArrayOfStrings - (Optional)

Paths(s) to search for files to include in the project.

Example:

.ProjectInputPaths = 'Code/Library/'

Example:

.ProjectInputPaths = { 'Code/Library/Folder1/' 'Code/Library/Folder2/' }

.ProjectInputPathsExclude - String or ArrayOfStrings - (Optional)

Path(s) to exclude when searching for files to include in the project.

Example:

.ProjectInputPathsExclude = 'Code/Library/SubDir/'

Example:

.ProjectInputPathsExclude = { 'Code/Library/SubDir1/' 'Code/Library/SubDir2/' }

.ProjectInputPathsRecurse - bool - (Optional)

Toggles whether to recurse into subdirectories of .ProjectInputPaths when finding files to add to the project.

Example:

.ProjectInputPathsRecurse = false

.ProjectPatternToExclude - String or ArrayOfStrings - (Optional)

Pattern(s) for files to exclude from project.

Example:

.ProjectPatternToExclude = '*/OSX/*'

Example:

.ProjectPatternToExclude = { '*/OSX/*' '*/Linux/*' }

.ProjectAllowedFileExtensions - String or ArrayOfStrings - (Optional)

Filter for file type(s) to include in the project.

Example:

.ProjectAllowedFileExtensions = { '*.cpp', '*.h' }

If not specified, the following filters will be used:

.ProjectAllowedFileExtensions = { '*.cpp', '*.hpp', '*.cxx', '*.hxx', '*.c', '*.h', '*.cc', '*.hh', '*.cp', '*.hp', '*.cs', '*.inl', '*.bff', '*.rc', '*.resx', '*.m', '*.mm', '*.cu', '*.asm', '*.s', '*.natvis', '*.editorconfig' }

.ProjectFiles - String or ArrayOfStrings - (Optional)

File(s) to explicitly include in the project.

Example:

.ProjectFiles = { 'Code/Library/SubDir/FileA.cpp' 'Code/Library/SubDir/FileA.h' }

.ProjectFilesToExclude - String or ArrayOfStrings - (Optional)

Files to exclude from the project (filtered from files discovered via ProjectInputPaths).

Example:

.ProjectFilesToExclude = { 'Code/Library/SubDir/FileB.cpp' 'Code/Library/SubDir/FileB.h' }

.ProjectBasePath - String or ArrayOfStrings - (Optional)

Path(s) to use as base for generation of folder hierarchy within project.

Example:

.ProjectBasePath = 'Code/Library/'

.ProjectFileTypes - Array of ProjectFileType Structures - (Optional)

File types can be specified if needed, for example for WinForms header files.

Example:

.ProjectFileType = [ .FileType = 'CppForm' .Pattern = '*\\Forms\\*.h' ] .ProjectFileTypes = { .ProjectFileType }

Multiple project configurations can be specified. This allows for per-config settings to be a configured.

.ProjectConfigs - Array of ProjectConfig Structure(s) - (Optional)

A list of project configuration structures in the following format:

.ProjectConfig = [ // Basic Options .Platform // Platform (e.g. Win32, X64, PS3 etc.) .Config // Config (e.g. Debug, Release etc.) .Target // (optional) Previously defined Build Target // Additional configuration options - see ProjectConfig section below ]

Example:

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

If no configurations are specified, the following defaults will be used:

.X86DebugConfig = [ .Platform = 'Win32' .Config = 'Debug' ] .X86ReleaseConfig = [ .Platform = 'Win32' .Config = 'Release' ] .X64DebugConfig = [ .Platform = 'X64' .Config = 'Debug' ] .X64ReleaseConfig = [ .Platform = 'X64' .Config = 'Release' ] .ProjectConfigs = { .X86DebugConfig, .X86ReleaseConfig, .X64DebugConfig, .X64ReleaseConfig }

The optional .Target option can be used to specify the associated compilation target. This will be used to automatically populate the Intellisense options for Intellisense.

Example:

.Target = 'MyProject-X64-Debug'

.ProjectReferences - String or ArrayOfStrings - (Optional)

References to assemblies can be specified. This may be necessary if mixing C#, Managed C++ and C++ projects.

Example:

.ProjectReferences = 'System.Core'

Example:

.ProjectReferences = { 'System.Core' 'System.Text' }

.ProjectProjectReferences - String or ArrayOfStrings - (Optional)

Add explicit references to projects not generated by FASTBuild. If your Visual Studio Solution mixes generated and manually created project files, you can set explicit references to them.

Example:

.ProjectProjectReferences = 'myproj1.csproj|{7cf4dd72-ddb6-4e8d-bc26-ffceb8c415a5}'

Example:

.ProjectProjectReferences = { 'myproj1.csproj|{7cf4dd72-ddb6-4e8d-bc26-ffceb8c415a5}' 'myproj2.csproj|{ffceb8c4-bc26-4932-ddb6-ff7cf4dd72a5}' }

.ProjectProjectImports - ArrayOfStructs - (Optional)

Additional .targets files can be imported into a Visual Studio project. This can be useful for better integration/debugging of non-native architectures.

Example:

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

NOTE: By default, the following project imports are active.

.ProjectImportPS4 = [ .Condition = "'$(ConfigurationType)' == 'Makefile' and Exists('$(VCTargetsPath)\Platforms\$(Platform)\SCE.Makefile.$(Platform).targets')" .Project = "$(VCTargetsPath)\Platforms\$(Platform)\SCE.Makefile.$(Platform).targets" ] .ProjectImportAndroid = [ .Condition = "'$(ConfigurationType)' == 'Makefile' and '$(AndroidAPILevel)' != '' and Exists('$(VCTargetsPath)\Application Type\$(ApplicationType)\$(ApplicationTypeRevision)\Android.Common.targets')" .Project = "$(VCTargetsPath)\Application Type\$(ApplicationType)\$(ApplicationTypeRevision)\Android.Common.targets" ] .ProjectProjectImports = { .ProjectImportPS4, .ProjectImportAndroid }

.ProjectGuid - String - (Optional)

Override default generated ProjectGuid.

By default, a Guid for a project will be generated automatically. If necessary, a Guid can be explicitly specified instead.

Example:

.ProjectGuid = '{7cf4dd72-ddb6-4e8d-bc26-ffceb8c415a5}'

.DefaultLanguage - String - (Optional)

Set the default language property. This may be necessary for XboxOne and WinRT applications.

Example:

.DefaultLanguage = 'en-US'

.ApplicationEnvironment - String - (Optional)

Set the application environment property. This may be necessary for XboxOne and WinRT applications.

Example:

.ApplicationEnvironment = 'title'

.ProjectSccEntrySAK - bool - (Optional)

Specifies if generic source control strings (SAK) should be generated in the project file.

Example:

.ProjectSccEntrySAK = true

Various options can be specified to control how each configuration is controlled. If the option is defined at the VCXProject level it will be applied to all configurations. If defined at the .ProjectConfig level, it will be used for the given project configuration. Options can be specified at both levels, allowing for individual ProjectConfigs to override as needed.

ProjectBuildCommand - String - (Optional)

Command to launch when "build project" is selected.

Example:

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

It can be convenient to take advantage of Visual Studio's runtime macro substitution to avoid having to manually specify this for every configuration.

Example:

.ProjectBuildCommand = 'cd ^$(SolutionDir)\..\..\Code\ & fbuild -ide -dist -cache ^$(ProjectName)-^$(Configuration)'

ProjectRebuildCommand - String - (Optional)

Command to launch when "rebuild project" is selected.

Example:

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

It can be convenient to take advantage of Visual Studio's runtime macro substitution to avoid having to manually specify this for every configuration.

Example:

.ProjectRebuildCommand = 'cd ^$(SolutionDir)\..\..\Code\ & fbuild -ide -clean -dist -cache ^$(ProjectName)-^$(Configuration)'

ProjectCleanCommand - String - (Optional)

Command to launch when "clean project" is selected.

Example:

.ProjectCleanCommand = 'fbuild -ide Clean-MyProject-X64-Debug'

It can be convenient to take advantage of Visual Studio's runtime macro substitution to avoid having to manually specify this for every configuration.

Example:

.ProjectCleanCommand = 'cd ^$(SolutionDir)\..\..\Code\ & fbuild -ide Clean-$(ProjectName)-^$(Configuration)'

Output - String - (Optional)

Output generated by compilation.

Example:

.Output = 'tmp/Debug/bin/MyExe.exe'

OutputDirectory - String - (Optional)

Output directory for Visual Studio

Example:

.OutputDirectory = 'tmp/Debug/bin/'

IntermediateDirectory - String - (Optional)

Intermediate directory for Visual Studio.

Example:

.IntermediateDirectory = 'tmp/'

BuildLogFile - String - (Optional)

Build log file for Visual Studio.

Example:

.BuildLogFile = 'tmp/^$(ProjectName)-^$(Configuration).log'

LayoutDir - String - (Optional)

Directory to prepare Layout (for XboxOne)

Example:

.LayoutDir = 'tmp/Layout/'

LayoutExtensionFilter - String - (Optional)

Files to filter from Layout (for XboxOne).

Example:

.LayoutExtensionFilter = '.pdb;.map;'

PreprocessorDefinitions - String - (Optional)

Preprocessor definitions for Intellisense can be manually specified. If the .Target for a configuration is specified, this will be populated automatically by detecting use of /D or -D in the compiler command line. Manual specification will override the automated detection.

Example:

.PreprocessorDefinitions = 'DEBUG;MY_LIB_DEFINE;__WINDOWS__;'

IncludeSearchPath - String - (Optional)

Include search paths for Intellisense can be manually specified. If the .Target for a configuration is specified, this will be populated automatically by detecting use of /I, -I, -isystem, -isystem-after, /imsvc, -imsvc, -idirafter, -iquote, /external:I or -external:I in the compiler command line. Manual specification will override the automated detection.

Example:

.IncludeSearchPath = 'Code/Core/;Code/Engine/;'

ForcedIncludes - String - (Optional)

Force included files for Intellisense can be manually specified.

Example:

.ForcedIncludes = 'forced.h'

AssemblySearchPath - String - (Optional)

Assembly search paths for Intellisense can be manually specified.

Example:

.AssemblySearchPath = '$WindowsSDK$/References/CommonConfiguration/Neutral'

ForcedUsingAssemblies - String - (Optional)

Forced using assemblies for Intellisense can be manually specified.

Example:

.ForcedUsingAssemblies = 'AssemblyName'

AdditionalOptions - String - (Optional)

Additional compiler options for Intellisense can be manually specified.

Example:

.AdditionalOptions = '/Zm100'

LocalDebuggerCommand - String - (Optional)

Explicitly specify the executable to launch when debugging. The LocalDebuggerCommand property of a Visual Studio project is usually set automatically by FASTBuild (extracted from the .Target specified per build configuration), but can be explicitily set via .LocalDebuggerCommand if desired.

Example:

.LocalDebuggerCommand = 'tmp/bin/MyExe.exe'

LocalDebuggerCommandArguments - String - (Optional)

Args passed to executable when debugging.

Example:

.LocalDebuggerCommandArguments = '-runFromVS'

LocalDebuggerWorkingDirectory - String - (Optional)

Working Dir for executable when debugging.

Example:

.LocalDebuggerWorkingDirectory = '/tmp/bin/'

LocalDebuggerEnvironment - String - (Optional)

Environment variables when debugging.

Example:

.LocalDebuggerEnvironment = '_NO_DEBUG_HEAP=1' // Disable debug heap

RemoteDebuggerCommand - String - (Optional)

Executable to launch when debugging remotely.

Specify the executable to launch when debugging remotely, when using the Windows Subsystem for Linux for example.

Example:

.RemoteDebuggerCommand = '/mnt/c/bin/myexe'

RemoteDebuggerCommandArguments - String - (Optional)

Args passed to remote executable when debugging.

Example:

.RemoteDebuggerCommandArguments = '-myArg'

RemoteDebuggerWorkingDirectory - String - (Optional)

Working Dir for remote executable when debugging.

Example:

.LocalDebuggerWorkingDirectory = '/mnt/c/bin/'

Xbox360DebuggerCommand - String - (Optional)

Debugger command for Xbox360 only.

DebuggerFlavor - String - (Optional)

Debugger flavor.

Example:

.DebuggerFlavor = 'WindowsLocalDebugger'

AumidOverride - String - (Optional)

Aumid override (for XboxOne).

Keyword - String - (Optional)

Keyword e.g. 'Android'

ApplicationType - String - (Optional)

ApplicationType e.g. 'Android'

ApplicationTypeRevision - String - (Optional)

ApplicationType e.g. '3.0'

TargetLinuxPlatform - String - (Optional)

Set the Linux platform type.

Example:

.TargetLinuxPlatform = 'Generic'

LinuxProjectType - String - (Optional)

Set the project type GUID for Linux.

Example:

.LinuxProjectType = '{D51BCBC9-82E9-4017-911E-C93873C4EA2B}'

PackagePath - String - (Optional)

Path to the package to be used for debugging.

AdditionalSymbolSearchPaths - String - (Optional)

Path to additional symbols to be used when debugging.

AndroidApkLocation - String - (Optional)

Location of APK for Android Game Development Extension.

AndroidDebugComponent - String - (Optional)

Debug component for Android Game Development Extension.

AndroidDebugTarget - String - (Optional)

Debug target for Android Game Development Extension.

AndroidJdb - String - (Optional)

JDB for Android Game Development Extension.

AndroidLldbPostAttachCommands - String - (Optional)

LLDB post attach commands for Android Game Development Extension.

AndroidLldbStartupCommands - String - (Optional)

LLDB startup commands for Android Game Development Extension.

AndroidPostApkInstallCommands - String - (Optional)

Post APK install commands for Android Game Development Extension.

AndroidPreApkInstallCommands - String - (Optional)

Pre APK install commands for Android Game Development Extension.

AndroidSymbolDirectories - String - (Optional)

Symbol dirs for Android Game Development Extension.

AndroidWaitForDebugger - String - (Optional)

Wait for Debugger for Android Game Development Extension.

LaunchFlags - String - (Optional)

Launch flags for Android Game Development Extension.

PlatformToolset - String - (Optional)

Specify PlatformToolset.

Example:

.PlatformToolset = 'v120'

DeploymentType - String - (Optional)

Specify deployment type for Xbox360.

DeploymentFiles - String - (Optional)

Specify files to add to deployment for Xbox360.

.RootNamespace - String - (Optional)

Set the RootNamespace for a project.

Example:

.RootNamespace = 'MyProject'