Understanding Xcode Project Files and the Xcodeproj Ruby Library

Introduction

The article begins by describing how CocoaPods resolves dependencies, downloads source code, and generates Xcode targets, then focuses on the composition of an Xcode project and how the xcodeproj bundle organizes its content.

Xcode Workspace

Before Xcode 4, a workspace was embedded inside a .xcodeproj bundle. After Xcode 4 the workspace became a separate bundle. Creating a Test.xcodeproj yields the following directory tree:

Test.xcodeproj
├── project.pbxproj
├── project.xcworkspace
│   └── contents.xcworkspacedata
│   └── xcuserdata/...
└── xcuserdata/...

The generated Test.xcworkspace contains only contents.xcworkspacedata , an XML file that references the project and the Pods project:

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

The xcuserdata folder stores user‑specific settings such as UserInterfaceState.xcuserstate and xcdebugger , which are commonly ignored in version control.

project.pbxproj

The project.pbxproj file is a legacy‑style Property List (plist) that records all project settings. It begins with an encoding marker and contains keys such as archiveVersion , objectVersion , and objects . The objectVersion maps to specific Xcode releases (e.g., 50 → Xcode 9.3).

Each entry in objects is identified by a 24‑bit hexadecimal GUID (referred to as an Xcode Object Identifier). These GUIDs must be unique across all projects to avoid conflicts in collaborative environments.

Property List Conversion

macOS provides the plutil utility to convert plists between formats, for example:

plutil -convert xml1 -s -r -o project.pbxproj.xml project.pbxproj

The conversion supports formats: xml1 , binary1 , json , swift , and json .

Xcodeproj Ruby Library

The Xcodeproj gem mirrors the structure of project.pbxproj with Ruby classes. The central class is Project , which exposes attributes such as archive_version , object_version , objects_by_uuid , and root_object .

Opening a project involves:

def self.open(path)
  path = Pathname.pwd + path
  raise "[Xcodeproj] Unable to open `#{path}` because it doesn't exist." unless Pathname.new(path).exist?
  project = new(path, true)
  project.send(:initialize_from_file)
  project
end

During initialization the plist is read, the root object is created, and all objects are stored in objects_by_uuid . Unknown archive or object versions raise errors.

Object Model and Attributes

All concrete objects inherit from AbstractObject , which provides isa , uuid , and a reference to the owning project. Attributes are declared via DSL methods:

attribute :project_dir_path, String, ''
has_one :main_group, PBXGroup
has_many :targets, AbstractTarget
has_many_references_by_keys :project_references, project_ref: PBXFileReference, product_group: PBXGroup

These declarations generate getter and setter methods that store values in internal hashes, ensuring type validation and marking the project dirty when modified.

Key Object Types

PBXFileReference represents a real file in the filesystem. Important fields are path , sourceTree (e.g., SOURCE_ROOT , <group> , <absolute> ), and lastKnownFileType :

F8DA09E31396AC040057D0CC /* main.m */ = {
  isa = PBXFileReference;
  fileEncoding = 4;
  lastKnownFileType = sourcecode.c.objc;
  path = main.m;
  sourceTree = SOURCE_ROOT;
};

PBXGroup is a virtual folder that can contain other groups, file references, or reference proxies. It may have a path or just a name (e.g., the “Frameworks” group):

F8E469631395739D00DB05C8 /* Frameworks */ = {
  isa = PBXGroup;
  children = (50ABD6EC159FC2CE001BE42C /* MobileCoreServices.framework */);
  name = Frameworks;
  sourceTree = "<group>";
};

Modifying an Xcode Project

Adding a source file involves locating (or creating) a group, creating a PBXFileReference , and attaching it to a target’s build phase:

project = Xcodeproj::Project.open(path)
target = project.targets.first
group = project.main_group.find_subpath('Xcodeproj/Test', true)
group.set_source_tree('SOURCE_ROOT')
file_ref = group.new_reference('MyClass.swift')
target.add_file_references([file_ref])
project.save

Adding a framework or library uses the frameworks_group and the appropriate build phase:

file_ref = project.frameworks_group.new_file('path/to/A.framework')
target.frameworks_build_phases.add_file_reference(file_ref)

file_ref = project.frameworks_group.new_file('path/to/libA.a')
target.frameworks_build_phases.add_file_reference(file_ref)

file_ref = project.frameworks_group.new_file('path/to/Assets.bundle')
target.resources_build_phase.add_file_reference(file_ref)

Conclusion

By abstracting real files into PBXFileReference and grouping them with PBXGroup , Xcode decouples the build system from the underlying filesystem, enabling stable references across large, multi‑target projects and simplifying collaborative development.