Xcode Project vs. Xcode Workspace - Differences

Question

I am trying to understand how the whole ecosystem of iOS works.
Until now, I could find an answer for most of my question (and trust me, there have been a lots of them), but for this one, there seems to be no clear answer yet.

What is the difference between XcodeProject and XcodeWorkspace files?

1. What is the difference between the two of them?
2. What are they responsible for?
3. Which one of them should I work with when I'm developing my Apps in team/alone?
4. Is there anything else I should be aware of in matter of these two files?

Tomboy

A huge issue is that SPM makes workspaces a bit useless, I think ... – Dunlin

Can't believe this is relevant after 9 years.... – Arnulfo

Answer 1

I think there are three key items you need to understand regarding project structure: Targets, projects, and workspaces. Targets specify in detail how a product/binary (i.e., an application or library) is built. They include build settings, such as compiler and linker flags, and they define which files (source code and resources) actually belong to a product. When you build/run, you always select one specific target.

It is likely that you have a few targets that share code and resources. These different targets can be slightly different versions of an app (iPad/iPhone, different brandings,…) or test cases that naturally need to access the same source files as the app. All these related targets can be grouped in a project. While the project contains the files from all its targets, each target picks its own subset of relevant files. The same goes for build settings: You can define default project-wide settings in the project, but if one of your targets needs different settings, you can always override them there:

Shared project settings that all targets inherit, unless they override it

Concrete target settings: PSE iPhone overrides the project’s Base SDK setting

In Xcode, you always open projects (or workspaces, but not targets), and all the targets it contains can be built/run, but there’s no way/definition of building a project, so every project needs at least one target in order to be more than just a collection of files and settings.

Select one of the project’s targets to run

In a lot of cases, projects are all you need. If you have a dependency that you build from source, you can embed it as a subproject. Subprojects can be opened separately or within their super project.

demoLib is a subproject

If you add one of the subproject’s targets to the super project’s dependencies, the subproject will be automatically built unless it has remained unchanged. The advantage here is that you can edit files from both your project and your dependencies in the same Xcode window, and when you build/run, you can select from the project’s and its subprojects’ targets:

If, however, your library (the subproject) is used by a variety of other projects (or their targets, to be precise), it makes sense to put it on the same hierarchy level – that’s what workspaces are for. Workspaces contain and manage projects, and all the projects it includes directly (i.e., not their subprojects) are on the same level and their targets can depend on each other (projects’ targets can depend on subprojects’ targets, but not vice versa).

Workspace structure

In this example, both apps (AnotherApplication / ProjectStructureExample) can reference the demoLib project’s targets. This would also be possible by including the demoLib project in both other projects as a subproject (which is a reference only, so no duplication necessary), but if you have lots of cross-dependencies, workspaces make more sense. If you open a workspace, you can choose from all projects’ targets when building/running.

You can still open your project files separately, but it is likely their targets won’t build because Xcode cannot resolve the dependencies unless you open the workspace file. Workspaces give you the same benefit as subprojects: Once a dependency changes, Xcode will rebuild it to make sure it’s up-to-date (although I have had some issues with that, it doesn’t seem to work reliably).

Your questions in a nutshell:

1) Projects contain files (code/resouces), settings, and targets that build products from those files and settings. Workspaces contain projects which can reference each other.

2) Both are responsible for structuring your overall project, but on different levels.

3) I think projects are sufficient in most cases. Don’t use workspaces unless there’s a specific reason. Plus, you can always embed your project in a workspace later.

4) I think that’s what the above text is for…

There’s one remark for 3): CocoaPods, which automatically handles 3rd party libraries for you, uses workspaces. Therefore, you have to use them, too, when you use CocoaPods (which a lot of people do).

Spurry

Can one project be part of two separate workspaces? Or if I want to share one project with two others would they need to all be part of the same workspace? – Premillennialism

Absolutely, a project can be a part of as many workspaces as you want. Adding a project to a workspace doesn't change anything about the project itself. So you have many options... all in one workspace, two workspaces that share one project, or two projects that have the shared project as a subproject. – Spurry

I don't have any experience with it, but the README says: "you retain full control over your project structure and setup", and "instead of integrating [dependencies] into a single workspace, [...] your dependencies must include their own Xcode project". In short: It doesn't touch your projects/workspaces at all, so I don't see how I should include it in the answer. The answer is still helpful if you use Carthage, especially as you have to decide how to structure your dependencies, but none of that is specific to Carthage. – Spurry

Well explained about Project hierarchy. If I remove/move subproject from the location then the subproject will be stays in the main project? stackoverflow.com/questions/40214505/… – Tetchy

The parent project file has a reference to the subproject, not a copy. If the subproject is removed, the parent won't find it anymore. Typically, you want to ensure on the file system level that the parent project has local copies of all its subprojects. Dependency managers such as CocoaPods or Carthage will do that for you, or you can use git submodules. – Spurry

Can a single project contains multiple workspaces? as like we re dragging one xcode project into other xcode project.. can we drag and drop one xcproject to other xcproject? – Sokul

Workspaces are sort of the highest level... you cannot put a workspace within a project, nor can you nest workspaces. While Xcode lets you drag a workspace into another project or workspace, it doesn't seem to do anything apart from showing the nested workspace as a flat file. – Spurry

Fantastic answer. Great you could take the time to outline it so clearly for us! – Fatso

Wow, one of the most impressive answers I've seen on stackoverflow. Crisp, clear and concise. – Hitandrun

After reading this answer, Apple's official Xcode Concepts article made a lot more sense to me. Thanks for posting this answer! – Jury

Awesome answer. However, I am coming form from React Native, I did not understand it fully, because we as React native developer don't have that much interaction with these files and structures. – Predesignate

My app uses a library that was downloaded with CocoaPods and I remember it saying that I have to load everything with the "xcworkspace" file from now on. A couple of months ago I accidently opened it with the "xcodeproj" file, which I've been using since but I didn't notice any difference and the library is still working fine. If everything still works the same (at least in my case with 1 proj + 1 library), why do they tell you to only use the workspace file? – Vasty

There any benefit to workspaces other than stated above if you're using swift package manager instead of CocoaPods? – Doyle

Love this answer, would be awesome to have a part of this acknowledge React Native, as we don't have much interaction with these files, but most of us probably landed here to know the answer to the question... "which one should I open to run my app on my device". From your answer, I'd guess that it's the .xcworkspace file with almost no exceptions to that. – Cynar

Thank you for taking the time and answering this question so clearly. – Alienable

For Flutter, people tend to use the workspace not the project. IDK why. – Togetherness

Answer 2

A workspace is a collection of projects. It's useful to organize your projects when there's correlation between them (e.g.: Project A includes a library, that is provided as a project itself as project B. When you build the workspace project B is compiled and linked in project A).
It's common to use a workspace in the popular CocoaPods. When you install your pods, they are placed inside a workspace, that holds your project and the pod libraries.

Fruiter

Answer 3

In brief

• Xcode 3 introduced subproject, which is parent-child relationship, meaning that parent can reference its child target, but no vice versa
• Xcode 4 introduced workspace, which is sibling relationship, meaning that any project can reference projects in the same workspace

Cooks

Answer 4

Xcode Workspace vs Project

1. What is the difference between the two of them?

Workspace is a set of projects

2. What are they responsible for?

Workspace is responsible for dependencies between projects. Project is responsible for the source code.

3. Which one of them should I work with when I'm developing my Apps in team/alone?

You choice should depends on a type of your project. For example if your project relies on CocoaPods dependency manager it creates a workspace.

4. Is there anything else I should be aware of in matter of these two files?

cross-project references^[About]

[Xcode components]

Pagination

in my case, I imported the google mobile ads sdk, everything works fine and build when i open workspace but it gives error when I open the project itself. what should i do ? – Oldie

Answer 5

When I used CocoaPods to develop iOS projects, there is a .xcworkspace file, you need to open the project with .xcworkspace file related with CocoaPods.

But when you Show Package Contents with .xcworkspace file, you will find the contents.xcworkspacedata file.

<?xml version="1.0" encoding="UTF-8"?>
<Workspace
   version = "1.0">
   <FileRef
      location = "group:BluetoothColorLamp24G.xcodeproj">
   </FileRef>
   <FileRef
      location = "group:Pods/Pods.xcodeproj">
   </FileRef>
</Workspace>

pay attention to this line:

location = "group:BluetoothColorLamp24G.xcodeproj"

The .xcworkspace file has reference with the .xcodeproj file.

Development Environment:

macOS 10.14
Xcode 10.1

No