XCodeProject

NOTE: XCodeProject generation is in Beta. Syntax may be changed in future versions as the capabilities are extended.

Summary

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 .ProjectPatternToExclude // (optional) Pattern(s) for diles 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 // Project Configurations .ProjectConfigs // Project configurations (see below) // Other Options .XCodeOrganizationName // (optional) Organization name to set in project } // ProjectConfigs - structs in the following format //-------------------------------------------------- [ .Config // Config to add to project (e.g. "Debug", "Release" etc) .Target // FASTBuild compilation target to associate with .Config ]
Details

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.

Basic Options

.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'
Input Options

.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/' }

.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' }
Compilation Options

.XCodeBuildToolPath - String - (Optional)

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

To commend line args to pass to FASTBuild when compiling can be specified.

Example:
.XCodeBuildToolArgs = '-ide -cache -summary $(FASTBUILD_TARGET)'
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.

.XCodeBuildWorkingDir - String - (Optional)

To location to set as a working directory for compilation.

Example:
.XCodeBuildToolPath = 'Code/'
If not specified, the default will be used:
.XCodeBuildToolPath = './'
Project Configurations

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

One or more build configuration must be specified. The .Target specifies which target FASTBuild will compile for a given .Config.

Example:
.DebugConfig = [ .Config = 'Debug' .Target = 'Lib-OSX-Debug' ] .ReleaseConfig = [ .Config = 'Release' .Target = 'Lib-OSX-Release' ] .ProjectConfigs = { .DebugConfig, .ReleaseConfig }
Other Options

.XCodeOrganizationName - String - (Required)

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'