Tuist logo
Edit page
Getting startedProject & WorkspaceProjectPackageTargetSource file listHeadersFile ListCore Data ModelPlatformProductInfoPlistInfoPlist.ValueTarget ActionPreset Build ConfigurationSchemeSettingsConfigurationCustom ConfigurationFileElementDefaultSettingsDeployment TargetDeployment DeviceWorkspacePathTarget ReferenceProject description helpersConfigurationDependenciesSet up the environmentEditing your projectsDependencies graphManaging versionsFrequently asked questions
Contributors

Project.swift

Projects are defined in Project.swift files, which we refer to as manifest files. Manifests need to import the framework ProjectDescription which contains all the classes and enums that are available for you to describe your projects. The snippet below shows an example project manifest:

let project = Project(name: "MyProject",
targets: [
Target(name: "App",
platform: .iOS,
product: .app,
bundleId: "io.tuist.App",
infoPlist: "Config/App-Info.plist",
sources: ["Sources/**"],
resources: [
"Resources/**",
.folderReference(path: "Stubs")
],
headers: Headers(public: ["Sources/public/A/**", "Sources/public/B/**"],
private: "Sources/private/**",
project: ["Sources/project/A/**", "Sources/project/B/**"]),
dependencies: [
.project(target: "Framework1", path: "../Framework1"),
.project(target: "Framework2", path: "../Framework2")
])
],
schemes: [
Scheme(name: "App-Debug",
shared: true,
buildAction: BuildAction(targets: ["App"]),
testAction: TestAction(targets: ["AppTests"]),
runAction: RunAction(executable: "App")),
Scheme(name: "App-Release",
shared: true,
buildAction: BuildAction(targets: ["App"]),
runAction: RunAction(executable: "App"))
],
additionalFiles: [
"Dangerfile.swift",
"Documentation/**",
.folderReference(path: "Website")
])

Project

A Project.swift should initialize a variable of type Project. It can take any name, although we recommend to stick to project. A project accepts the following attributes:

Name

Name of the project. It's used to determine the name of the generated Xcode project.

StringNo
Packages

List of Swift Packages used by the project.

[Package]Yes[]
Targets

List of targets within the project.

[Target]No[]
Schemes

List of files to include in the project - these won't be included in any of the build phases

[Scheme]Yes[]
Settings

Project build settings and configuration files

SettingsYes
AdditionalFiles

List of files to include in the project - these won't be included in any of the build phases

[FileElement]Yes[]

Package

You can add Swift Packages very similarly to how you add dependencies in a Package.swift:

For remote:

.package(url: "https://github.com/tuist/XcodeProj", .exact("6.7.0"))
.package(url: "https://github.com/tuist/XcodeProj", from: "6.7.0")
.package(url: "https://github.com/tuist/XcodeProj", "6.6.1"..<"6.8.0")

For local:

.package(path: "MyLibrary")

Targets can then depend on products from these Swift Packages. See Dependencies

Package.resolved

Tuist creates a .package.resolved file, so your team can share the same versions of dependencies without committing your workspace.

Target

Each target in the list of project targets can be initialized with the following attributes:

Name

The name of the target. The Xcode project target and the derivated product take the same name.

StringNo
Platform

The platform the target product is built for.

PlatformNo
Product

The type of build product this target will output.

ProductNo
Product Name

The built product name.

StringYes$(TARGET_NAME)
Deployment Target

The minimum iOS version your product will support.

DeploymentTargetYesnil
Bundle id

The product bundle identifier.

StringNo
Info plist

Relative path to the Info.plist

PathNo
Resources

List of files to include in the resources build phase

[FileElement]Yes[]
Headers

The target headers

HeadersYesnil
Entitlements

Path to the entitlement file.

PathYesnil
Actions

Target actions allow defining extra script build phases.

[TargetAction]Yes[]
Dependencies

List of target dependencies

[TargetDependency]Yes[]
Sources

Source files that are compiled by the target

SourceFilesListNo
Settings

Target build settings and configuration files.

SettingsYesnil
Core Data models

Core Data models.

[CoreDataModel]Yes[]
Environment

List of variables that will be set to the scheme that Tuist automatically generates for the target.

[String: String]Yes[:]
import ProjectDescription
let target = Target(name: "App",
platform: .iOS,
product: .app,
bundleId: "io.tuist.App",
infoPlist: "Info.plist",
sources: "Sources/**",
dependencies: [])

Source file list

It represents a list of source files that are part of a target:

Globs

Path to the source files. They are represented by a glob pattern and the compiler flags.

[SourceFileGlob]No
ExpressibleByStringLiteral and ExpressibleByArrayLiteral

The list of source files can be initialized with a string that represents the glob pattern, or an array of strings, which represents a list of glob patterns. In both cases the comiler flags will have no value.

Patterns matching the same paths

If multiple patterns match the same paths, the latest one takes preference over the others. That also means that the latest compiler flags will be applied.

Source file glob

It represents a glob pattern that refers to source files and the compiler flags (if any) to be set in the build phase:

Glob

Glob pattern to the source files.

PathNo
Compiler flags

The compiler flags to be set to the source files in the sources build phase.

StringYesnil

Headers

It represents the target headers:

Public

Relative glob pattern that points to the public headers

FileListYesnil
Private

Relative glob pattern that points to the private headers

FileListYesnil
Project

Relative glob pattern that points to the project headers

FileListYesnil

File List

It represents a list of glob patterns that refer to files:

Globs

Glob pattern to the files.

[Path]No

Core Data Model

The CoreDataModel type represents a Core Data model:

Path

Relative path to the Core Data model.

PathNo
Current version

Current version without the extension.

StringNo

Platform

The platform type represents the platform a target is built for. It can be any of the following types:

CaseDescription
.iOSAn iOS platform.
.macOSA macOS platorm.
.tvOSA tvOS platform.
.watchOSA watchOS platform.

Product

The type of build product this target will output. It can be any of the following types:

CaseDescription
.appAn application.
.staticLibraryA static library.
.dynamicLibraryA dynamic library.
.frameworkA dynamic framework.
.staticFrameworkA static framework. This is a regular framework product however is configured to be statically linked.
.unitTestsA unit tests bundle.
.uiTestsA UI tests bundle.
.bundleA custom bundle. (Currently only iOS resource bundles are supported)
.appExtensionAn application extension.
.stickerPackExtensionA sticker pack extension.
.watch2AppA Watch application. (watchOS platform only)
.watch2ExtensionA Watch application extension. (watchOS platform only)

InfoPlist

The InfoPlist model represents a target Info.plist file. It can have any of the following values:

CaseDescription
.file(path: Path)The path to an existing Info.plist file
.dictionary([String: InfoPlist.Value])A dictionary with the Info.plist content. Tuist generates the Info.plist file at the generation time.
.extendingDefault(with: [String: InfoPlist.Value])It indicates Tuist to provide the default content for the target the InfoPlist belongs to, and extend it with the given values.
ExpressibleByStringLiteral

The InfoPlist model conforms the ExpressibleByStringLiteral protocol, which means that it can be initialized with a String. In that case, the string is the path to the Info.plist file.

InfoPlist.Value

It represents the values of the InfoPlist file dictionary. The reason this type exists is to ensure that the values used to define the content of the dynamically generated Info.plist files ar valid:

CaseDescription
.string(String)It represents a string value.
.integer(Int)It represents an integer value.
.boolean(Bool)It represents a boolean value.
.dictionary([String: InfoPlist.Value])It represents a dictionary value.
.array([InfoPlist.Value])It represents an array value.
ExpressiveByLiteral

InfoPlist.Value conforms to the ExpressiveByLiteral protocols and therefore, it can be initialized with an instance of the primitive type that they encapsulate.

Target Action

Target actions, represented as target script build phases, are useful to define actions to be executed before of after the build process of a target.

CaseDescription
.pre(tool: String, arguments: String..., name: String, inputPaths: [Path], inputFileListPaths: [Path], outputPaths: [Path], outputFileListPaths: [Path])Action executed before the target-specific build phases where tool is the name of the tool to be executed.
.pre(path: Path, arguments: String..., name: String, inputPaths: [Path], inputFileListPaths: [Path], outputPaths: [Path], outputFileListPaths: [Path])Action executed before the target-specific build phases where path is the path to the tool to be executed.
.post(tool: String, arguments: String..., name: String, inputPaths: [Path], inputFileListPaths: [Path], outputPaths: [Path], outputFileListPaths: [Path])Action executed after all the target-specific build phases where tool is the name of the tool to be executed.
.post(path: Path, arguments: String..., name: String, inputPaths: [Path], inputFileListPaths: [Path], outputPaths: [Path], outputFileListPaths: [Path])Action executed after all the target-specific build phases where path is the path to the tool to be executed.

The following example shows the definition of an action that runs the my_custom_script.sh passing the argument "hello":

.pre(path: "my_custom_script.sh", arguments: ["hello"], name: "My Custom Script Phase")

The following example shows the definition of an action that runs the my_custom_script.sh defining input and output files:

.pre(path: "my_custom_script.sh", name: "My Custom Script Phase", inputFileListPaths: [ "Data/Cars.raw.json", "Data/Drivers.raw.json" ], outputFileListPaths: [ "Data/Cars.swift", "Data/Drivers.swift" ])

Preset Build Configuration

It represents the default build configurations available:

CaseDescription
.debugDebug build configuration, traditionally used during local development.
.releaseRelease build configuration.

Scheme

A Scheme defines a collection of targets to Build, Run, Test, Profile, Analyze and Archive:

Name

The name of the scheme.

StringNo
Shared

Marks the scheme as shared (i.e. one that is checked in to the repository and is visible to xcodebuild from the command line).

BoolYestrue
Build action

Action that builds the project targets.

BuildActionYesnil
Run action

Action that runs project built products.

RunActionYesnil
Test action

Action that runs the project tests.

TestActionYesnil
Archive action

Action that runs the project archive.

ArchiveActionYesnil
Auto-generation of schemes

Tuist will auto-generate a scheme for each target by default in addition to any defined schemes.

Schemes & Configurations

When generating the default target schemes, the 'Debug' configuration is used for the Run, Test and Analyze actions and the 'Release' configuration is used for the Profile & Archive actions. If those configurations aren't specified, the first (alphabetically ordered) custom configuration with the corresponding variant is selected in their place.

Build Action

It represents the scheme action that builds targets:

Targets

A list of targets to build, which are defined in the Project.

[TargetReference]No
Pre-actions

A list of actions that are executed before starting the build process.

[ExecutionAction]Yes[]
Post-actions

A list of actions that are executed after the build process.

[ExecutionAction]Yes[]

Run action

It represents the scheme action that runs the built products on the supported platforms:

Config

Indicates the build configuration the product should run with.

PresetBuildConfigurationYes.debug
Executable

The name of the executable or target to run.

TargetReferenceYesnil
Arguments

Commandline arguments passed on launch and environment variables.

ArgumentsYesnil

Alternatively, when leveraging custom configurations, the configuration name can be explicitly specified:

Configuration Name

Indicates the build configuration the product should run with.

StringNo

Test Action

Targets

A list of testable targets, that are targets which are defined in the project with testable information.

[TestableTarget]No[]
Arguments

Commandline arguments passed on launch and environment variables.

ArgumentsYesnil
Build configuration

Build configuration to run the test with.

PresetBuildConfigurationYes.debug
Coverage

Whether the scheme should or not gather the test coverage data.

BoolYesfalse
codeCoverageTargets

A list of targets you want to gather the test coverage data for them, which are defined in the project.

[TargetReference]Yes[]
Pre-actions

A list of actions that are executed before starting the tests-run process.

[ExecutionAction]Yes[]
Post-actions

A list of actions that are executed after the tests-run process.

[ExecutionAction]Yes[]

Alternatively, when leveraging custom configurations, the configuration name can be explicitly specified:

Configuration Name

Indicates the build configuration to run the test with.

StringNo

Execution Action

Scheme run scripts can be defined with the following attributes:

Title

Name of a script.

StringYes'Run Stript'
Script text

An inline shell script.

StringNo
Target

Name of the build or test target that will provide the action's build settings.

TargetReferenceYesnil

TestableTarget

Testable target descibe target and tests information.

Target

The target name and its project path.

TargetReferenceNo
Skipped

Skip test target from TestAction.

BoolYesfalse
Parallelizable

Execute tests in parallel.

BoolYesfalse
RandomExecutionOrdering

Execute tests in random order.

BoolYesfalse

Arguments

Arguments contain commandline arguments passed on launch and Environment variables.

Environment

The environment variables that are passed by the scheme when running a scheme action.

[String: String]Yes[:]
Launch

Commandline launch arguments where the key is a launch argument and the value is a boolean indicating if it's enabled.

[String: Bool]Yes[:]

Archive Action

Configuration Name

Indicates the build configuration to run the archive with.

StringNo
Reveal Archive in Organizer

If set to true, Xcode will reveal the Organizer on completion.

BoolYestrue
Custom Archive Name

Set if you want to override Xcode's default archive name.

StringYesnil
Pre-actions

A list of actions that are executed before starting the archive process.

[ExecutionAction]Yes[]
Post-actions

A list of actions that are executed after the archive process.

[ExecutionAction]Yes[]

Settings

A Settings object contains an optional dictionary with build settings and relative path to an .xcconfig file. It is initialized with the following attributes:

Base

A dictionary with build settings that are inherited from all the configurations.

[String: SettingValue]Yes[:]
Debug

The debug configuration settings.

ConfigurationYesnil
Release

Same as debug but for the release configuration.

ConfigurationYesnil
Default settings

An enum specifying the set of default settings.

DefaultSettingsYes.recommended

To specify multiple configurations beyond the default Debug and Release configuration (e.g. Debug, Beta, Release), Settings can alternatively be initialized with the following attributes:

Base

A dictionary with build settings that are inherited from all the configurations.

[String: String]Yes[:]
Configurations

A list of custom configurations

[CustomConfiguration]No
Default settings

An enum specifying the set of default settings.

DefaultSettingsYes.recommended
Custom Configurations

The list of custom configurations should have unique names and can't be empty. Please use the alternate settings initializer to leverage the default Debug & Release configurations.

Configuration

A Configuration object describes the build settings and the .xcconfig file of a project or target. It is initialized with the following attributes:

Settings

A dictionary that contains the build settings

[String: SettingValue]Yes[:]
Path

The path to the xcconfig file

PathYesnil

Custom Configuration

A CustomConfiguration allows specifying a named build configuration.

This is similar to Configuration, however allows specifying a custom name (e.g. "Beta") and configuration variant (.debug or .release) to help Tuist select the most appropriate default build settings.

For example, a .debug configuration would get SWIFT_OPTIMIZATION_LEVEL = -Onone whereas a .release would get SWIFT_OPTIMIZATION_LEVEL = -Owholemodule.

CaseDescription
.debug(name: String, settings: [String: String], xcconfig: Path?)A custom debug configuration
.release(name: String, settings: [String: String], xcconfig: Path?)A custom release configuration

SettingValue

A SettingValue can be one of the following options:

CaseDescription
.string(String)A single setting value for example "DEBUG=1".
.array([String])Multi-value setting value for example ["$(inherited)", "DEBUG=1"].

It conforms the ExpressibleByStringLiteral and ExpressibleByArrayLiteral protocols and therefore it can be initialized with a string or an array directly.

FileElement

A FileElement can be one of the following options:

CaseDescription
.glob(pattern: Path)A file path (or glob pattern) to include. For convenience, a string literal can be used as an alternate way to specify this option.
.folderReference(path: Path)A directory path to include as a folder reference.

DefaultSettings

A DefaultSettings can be one of the following options:

CaseDescription
.recommendedRecommented settings including warning flags to help you catch some of the bugs at the early stage of development.
.essentialA minimal set of settings to make the project compile without any additional settings for example 'PRODUCT_NAME' or 'TARGETED_DEVICE_FAMILY'.
.noneTuist won't generate any build settings for the target or project.
Essential Settings

The .essential option can be used in the event all warnings are defined in an xcconfig file to prevent Tuist from overriding them at the project or target level.

None settings

Projects may fail to compile if some essential settings are missing. Use .none only if you are specifying all the necessary build settings manually or via xcconfig files.

Deployment Target

The DeploymentTarget model represents the minimum operating system version your product will support. It can have any of the following values:

CaseDescription
.iOS(targetVersion: String, devices: DeploymentDevice)The minimum iOS version and the list of devices your product will support.
.macOS(targetVersion: String)The minimum macOS version your product will support.

Deployment Device

The DeploymentDevice model represents the device your product will support. It can have any of the following values:

CaseDescription
.iphoneAn iPhone device.
.ipadAn iPad device.
.macA mac device.

Workspace.swift

By default, tuist generate generates an Xcode workspace that has the same name as the current project. It includes the project and all its dependencies. Tuist allows customizing this behaviour by defining a workspace manifest within a Workspace.swift file.

Workspace manifests allow specifying a list of projects to generate and include in an Xcode workspace. Those projects don’t necessarily have to depend on one another.

Additionally, files and folder references (such as documentation files) can be included in a workspace manifest.

The snippet below shows an example workspace manifest:

import ProjectDescription
let workspace = Workspace(name: "CustomWorkspace",
projects: [
"App",
"Modules/**"
],
schemes: [
Scheme(name: "Workspace-App",
shared: true,
buildAction: BuildAction(targets: [.project(path: "App", target: "App")], preActions: []),
testAction: TestAction(targets: [TestableTarget(target: .project(path: "App", target: "AppTests"))]),
runAction: RunAction(executable: .project(path: "App", target: "App")),
archiveAction: ArchiveAction(configurationName: "Debug", customArchiveName: "Something2"))
],
additionalFiles: [
"Documentation/**",
.folderReference(path: "Website")
])

A Workspace.swift file can reside in any directory (including a project directory).

Workspace

A Workspace.swift should initialize a variable of type Workspace. It can take any name, although we recommend to stick to workspace. A workspace accepts the following attributes:

Name

Name of the workspace. It’s used to determine the name of the generated Xcode workspace.

StringNo
Projects

List of paths (or glob patterns) to projects to generate and include within the generated Xcode workspace.

[Path]No
Schemes

List of custom schemes to include in the workspace

[Scheme]Yes[]
AdditionalFiles

List of files to include in the workspace - these won't be included in any of the projects or their build phases.

[FileElement]Yes[]

Path

A path represents a path to a file, directory, or a group of files represented by a glob expression. Paths can be relative and absolute. We discourage using absolute paths because they create a dependency with the environment where they are defined.

CaseDescription
.relativeToCurrentFile(String)Initialize a path that is relative to the file that defines the path.
.relativeToManifest(String)Initialize a path that is relative to the directory that contains the manifest file being loaded, for example the directory that contains the Project.swift file.
.relativeToRoot(String)Initialize a path that is relative to the closest directory that contains a Tuist or a .git directory.
ExpressibleByStringLiteral

The path can be initialized with a plain string. It's equivalent to using .relativeToManifest. except when the path starts with //, in which case the path is considered relative to the root directory.

Target Reference

A target within a specified project. The project is specified through the path and should contain the target name.

path

Path to the target's project directory.

PathYesWorkspace or project path.
name

Name of the target.

StringNo