Debugging the communication between Xcode and XCBBuildService

Xcode and xcodebuild use an internal service named XCBBuildService to perform build tasks. The contract between Xcode and XCBBuildService has been leveraged by some organizations, such as to proxy calls to other build systems like Bazel. More recently, Apple has utilized it to add support for their new build system, swift-build, which we discussed in this blog post.

As a developer, this is generally not something you need to worry about. However, at Tuist, understanding this system has been on our backlog for some time, as we wanted to explore introducing optimizations and telemetry at a lower layer of the build process. The introduction of swift-build has shifted our focus, as it now makes more sense for us to explore that layer.

While working with one of Tuist's customers, we observed some unusual behaviors, including Xcode projects and xcodebuild processes hanging, without a clear explanation. This prompted us to investigate the communication between Xcode and XCBBuildService and build a small utility to help debug it.

XCBBuildService has been recently open sourced and rebranded as SWBBuildService.

The Format

Xcode spawns XCBBuildService as a system process and communicates with it through standard pipelines. Messages are formatted using MessagePack, a format similar to JSON but smaller and faster.

The types of messages exchanged can be found in the Mobile Native Foundation's XCBBuildServiceProxyKit project or in the SWBProtocol target of swift-build. Among others, you will find messages for:

• Requesting indexing information
• Pinging the service
• Listing the available sessions (since multiple can exist)
• Starting a build operation
• Notifying about the completion of a build operation

As mentioned earlier, you do not directly interact with these messages. Xcode and xcodebuild, acting as presentation layers, translate these internals into a debuggable UI or CLI output.

Debugging Messages with XCBLoggingBuildService

To facilitate debugging this communication, we built a new Swift package, XCBLoggingBuildService. It serves as a simple wrapper around XCBBuildService, logging the messages exchanged between Xcode and the service.

You can use it with Xcode or xcodebuild by following these steps:

First, clone and build the project the repository:

You can then use it with xcodebuild or Xcode

The logs are saved in /tmp/XCBLoggingBuildService.log. You can monitor them in real time using:

What's next

In the coming months, we'll explore the internals of swift-build, its extensibility, and the capabilities it offers for Tuist to optimize your projects and enhance telemetry for better decision-making. Of course, we'll document our learnings in this blog.