FASTBuild - Function Reference

Generates an XCode Project file, allowing integration of FASTBuild into XCode.

XCodeProject( 'alias' ) // (optional) Alias { // Basic Options .ProjectOutput // Path to project.pbxproj file to be created // Input Options .ProjectInputPaths // (optional) Path(s) containing files to include in project .ProjectInputPathsExclude // (optional) Path(s) 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 .ProjectFiles // (optional) File(s) to include in project .ProjectFilesToExclude // (optional) File(s) to exclude from project .ProjectBasePath // (optional) Base path(s) to use to build folder hierarchy in project .ProjectAllowedFileExtensions // (optional) File extension pattern(s) to include in project (see below for default) // Compilation Options .XCodeBuildToolPath // (optional) Path to FASTBuild executable .XCodeBuildToolArgs // (optional) Args to pass to FASTBuild .XCodeBuildWorkingDir // (optional) Working dir to set when invoking FASTBuild // Debugging Options .XCodeDocumentVersioning // (optional) Enable "Document Versioning" (default: false) .XCodeCommandLineArguments // (optional) Enabled command line options for debug target .XCodeCommandLineArgumentsDisabled // (optional) Disabled command line options for debug target // Other Options .XCodeOrganizationName // (optional) Organization name to set in project // Project Configurations .ProjectConfigs // Project configurations (see below) } // ProjectConfigs - structs in the following format //-------------------------------------------------- [ .Config // Config to add to project (e.g. "Debug", "Release" etc) .Target // (optional) FASTBuild compilation target to associate with .Config .XCodeBaseSDK // (optional) SDK for compilation target (e.g. "iphoneos", "macosx" ) .XCodeDebugWorkingDir // (optional) Working dir for target when debugging .XCodeIphoneOSDeploymentTarget // (optional) iOS deployment version ]

XCodeProject generates an XCode Project file, including files and other projects as specified via the various input options, to allow integration of FASTBuild into XCode. Project generated are compatible with XCode version 6.0 and later.

The XCode project file only specifies the FASTBuild target to invoke for compilation. It does not itself control the compilation settings used: they are still managed exclusively by the FASTBuild configuration. The generation of XCode projects is useful to allow the XCode IDE to be used as an editor and debugger while keeping FASTBuild as the underlying build system.

.ProjectOutput - String - (Required)

The output location of the project.pbxproj file. Note that a valid XCode Project requires a project.pbxproj file be created within a specifically named folder.

Example:

.ProjectOutput = 'tmp/XCode/MyProject.xcodeproj/project.pbxproj'

.ProjectInputPaths - String or ArrayOfStrings - (Optional)

One or more directories can be specified to search for files and add to a project. Searching is recursive.

Example:

.ProjectInputPaths = 'Code/Lib/Folder/'

Or:

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

.ProjectInputPathsExclude - String or ArrayOfStrings - (Optional)

One or more directories can be specified to ignore during directory traversal.

Example:

.ProjectInputPathsExclude = 'Code/Lib/FolderToExclude/'

Or:

.ProjectInputPathsExclude = { 'Code/Lib/FolderToExclude1/' 'Code/Lib/FolderToExclude2/' }

.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)

One or more patterns can be specified to ignore during directory traversal.

Example:

.ProjectPatternToExclude = '*/OSX/*'

Or:

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

.ProjectFiles - String or ArrayOfStrings - (Optional)

One or more files can be explicitly listed for inclusion in the project.

Example:

.ProjectFiles = 'Code/Libraries/Lib/A.cpp'

Or:

.ProjectFiles = { 'Code/Libraries/Core/A.cpp' 'Code/Libraries/Core/B.cpp' }

Additionally, XCodeProjects can be embedded within other XCodeProjects:

.ProjectFiles = { 'Core-xcode' // Assume alias to previously defined XCodeProject 'Engine-xcode' // Assume alias to previously defined XCodeProject }

.ProjectFilesToExclude - String or ArrayOfStrings - (Optional)

One or move files can be specified to ignore during directory traversal.

Example:

.ProjectFilesToExclude = 'Code/Lib/FileToExclude.cpp'

Or:

.ProjectFilesToExclude = { 'Code/Lib/FileToExclude1.cpp' 'Code/Lib/FileToExclude2.cpp' }

.ProjectBasePath - String or ArrayOfStrings - (Optional)

One or move directories can be specified as the root of the folder hierarchy that will be created within the generated project.

Example:

.ProjectBasePath = 'Code/Lib/'

Or:

.ProjectBasePath = { 'Code/Lib1/' 'Code/Lib2/' }

.ProjectAllowedFileExtensions - String or ArrayOfStrings - (Optional)

One or move wildcard patterns can be specified to restrict which files will be included in the project during directory traversal. Explicitly listed files (.ProjectFiles) will always be included.

Example:

.ProjectAllowedFileExtensions = '*.cpp'

Or:

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

If not specified, the default 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' }

.XCodeBuildToolPath - String - (Optional)

The location of the FASTBuild executable to invoke can be specified.

Example:

.XCodeBuildToolPath = '../Build/FBuild'

If not specified, the default will be used:

.XCodeBuildToolPath = './FBuild'

.XCodeBuildToolArgs - String - (Optional)

The command line args to pass to FASTBuild when compiling can be specified.

Example:

.XCodeBuildToolArgs = '-ide -cache -summary OSX64-All'

If not specified, the default will be used:

.XCodeBuildToolArgs = '-ide ^$(FASTBUILD_TARGET)'

FASTBUILD_TARGET is a special per-configuration symbol that will be replaced (by XCode) with the .Target being compiled. FASTBuild automatically defines this symbol correctly for each build configuration.
Note that the $ is escaped so that it's not interpretted by FASTBuild as the beginning of a variable substitution.

.XCodeBuildWorkingDir - String - (Optional)

The location to set as a working directory for compilation.

Example:

.XCodeBuildToolPath = 'Code/'

If not specified, the default will be used:

.XCodeBuildToolPath = './'

.XCodeDocumentVersioning - Boolean - (Optional)

Controls whether the "Document Versionsing" checkbox is enabled.

By default (non-FASTBuild) XCode projects have this option set, which causes XCode to pass additional args on the command line to the process when debugging. This is usually not desired, so FASTBuild suppresses this by default. The option can be re-enabled if needed.

Example:

.XCodeDocumentVersioning = true

.XCodeCommandLineArguments - String or ArrayOfStrings - (Optional)

Specify command line arguments passed to the process when debugging.

Example:

.XCodeCommandLineArguments = { '-Arg1', '-Arg2' }

NOTE: This option (and .XCodeCommandLineArgumentsDisabled) is stored in the .xcscheme file for the project, which also contains other user-edited settings. As such, while FASTBuild will generate this file if missing, it will not overwrite it when it changes (so as not to overwrite other user edited settings). The .xcscheme can be deleted to force regeneration.

.XCodeCommandLineArgumentsDisabled - String or ArrayOfStrings - (Optional)

Specify command line arguments passed to the process when debugging (same as .XCodeCommandLineArguments), but disable them by default.

.XCodeOrganizationName - String - (Optional)

The organization name which appears in the generated project can be set.

Example:

.XCodeOrganizationName = 'MyCompany'

If not specified, the default will be used:

.XCodeOrganizationName = 'Organization'

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

One or more build configuration must be specified. Each configuration can be selected in the XCode UI and the various properties specify how to generate configuration info for XCode.

Example:

.DebugConfig = [ ... ] // See below for options .ReleaseConfig = [ ... ] // See below for options .ProjectConfigs = { .DebugConfig, .ReleaseConfig }

.Config - String - (Required)

The name of the build configuration. This will be displayed in various places in the XCodeUI.

Example:

.DebugConfig = [ .Config = 'Debug' ...

.Target - String - (Required)

The target defined in the .bff which should be compiled for this configuration.

Example:

.DebugConfig = [ .Target = 'MyApp-OSX-Debug' ...

.XCodeBaseSDK - String - (Optional)

The SDK associate with the target. This controls the options available for launching an executable for debugging and must be specified if the target is not 'macosx'.

Example:

.DebugConfig = [ .XCodeBaseSDK = 'iphoneos' ...

.XCodeDebugWorkingDir - String - (Optional)

The working directory to be used when debugging this build configuration. If not specified, the path to the executable created by .Target will be used.

Example:

.DebugConfig = [ .XCodeDebugWorkingDir = 'path/path' ...

.XCodeIphoneOSDeploymentTarget - String - (Optional)

The iOS version required for deployment can be overridden from the XCode default.

Example:

.DebugConfig = [ .XCodeIphoneOSDeploymentTarget = '12.0' ...