A workspace is an Xcode document that groups projects and other documents so you can work on them together. A workspace can contain any number of Xcode projects, plus any other files you want to include. In addition to organizing all the files in each Xcode project, a workspace provides implicit and explicit relationships among the included projects and their targets.

Workspaces Extend the Scope of Your Workflow

A project file contains pointers to all the files in the project, along with build configurations and other project information. In Xcode 3 and earlier, the project file is always the root of the group and file structure hierarchy. Although a project can contain references to other projects, working on interrelated projects in Xcode 3 is complicated; most workflows are confined to a single project. In Xcode 4 and later, you have the option of creating a workspace to hold one or more projects, plus any other files you wish to include.

In addition to providing access to all the files in each included Xcode project, a workspace extends the scope for many important Xcode workflows. For example, because indexing is done across the whole workspace, code completion, Jump to Definition, and all other content-aware features work seamlessly through all projects in the workspace. Because refactoring operations act across all the content of the workspace, you can refactor the API in a framework project and in several application projects that use that framework all in one operation. When building, one project can make use of the products of other projects in the workspace.

The workspace document contains pointers to the included projects and other files, but no other data. A project can belong to more than one workspace. The figure shows a workspace containing two Xcode projects (Sketch and TextEdit) plus a documentation project (Xcode4TransGuideDocPlan).

Projects in a Workspace Share a Build Directory

By default, all the Xcode projects in a workspace are built in the same directory, referred to as the workspace build directory. Each workspace has its own build directory. Because all of the files in all of the projects in a workspace are in the same build directory, all of these files are visible to each project. Therefore, if two or more projects use the same libraries, you don’t need to copy them into each project folder separately.

Xcode examines the files in the build directory to discover implicit dependencies. For example, if one project included in a workspace builds a library that is linked against by another project in the same workspace, Xcode automatically builds the library before building the other project, even if the build configuration does not make this dependency explicit. You can override such implicit dependencies with explicit build settings if necessary. For explicit dependencies, you must create project references.

Each project in a workspace continues to have its own independent identity. To work on a project without affecting—or being affected by—the other projects in the workspace, you can open the project without opening the workspace, or you can add the project to another workspace. Because a project can belong to more than one workspace, you can work on your projects in any number of combinations without having to reconfigure any of the projects or workspaces.

You can use the workspace’s default build directory or you can specify one. Note that if a project specifies a build directory, that directory is overridden by the build directory of whatever workspace the project is in at the time you build the project.