What is an .xcworkspace file?

Xcode often creates a “SomeProject.xcworkspace” file. What is it?

Each .xcworkspace file corresponds to a “workspace” created in Xcode via File > New > Workspace.... You can open them in Xcode, just like you can open projects.

But it’s not actually a file, it’s a directory. Only Finder attempts to confuse you by displaying directories with this extension as files.

The important file is SomeProject.xcworkspace/contents.xcworkspacedata. This is an XML file, which looks like:

<?xml version="1.0" encoding="UTF-8"?>
<Workspace version="1.0">
   <FileRef ...></FileRef>
   <Group ...>
     <FileRef ...></FileRef>
   <FileRef ...></FileRef>

That is, an arbitrary tree, where the root is a <Workspace> element, the leaves are <FileRef> elements, and everything in-between is a <Group>.

<Groups> are like directories; they are displayed as a directory tree in the “Project navigator” when you open the workspace in Xcode. An example of a <Group>:

<Group location="container:" name="foobar">

The name property is the title in the Project navigator. (What is container:? Who knows?!)

The <FileRef> elements are like “files” in those “directories”. An example of a <FileRef>:

<FileRef location="group:foo/bar/SomeProject.xcodeproj"></FileRef>

What is that group: protocol? It includes an XCode project as the sole member of a “group”.

The path foo/bar/SomeProject.xcodeproj is relative to the directory containing the .xcworkspace. So if you have $ROOT/SomeProject.xcworkspace/contents.xcworkspacedata containing a <FileRef location="group:foo/bar/SomeProject.xcodeproj"></FileRef>, the relative path resolves to $ROOT/foo/bar/SomeProject.xcodeproj.

Tagged #xcode, #programming.

Similar posts

More by Jim

Want to build a fantastic product using LLMs? I work at Granola where we're building the future IDE for knowledge work. Come and work with us! Read more or get in touch!

This page copyright James Fisher 2016. Content is not associated with my employer. Found an error? Edit this page.