xcode-build-server

To integrate Xcode with sourcekit-lsp, use the config command in your workspace directory. This creates or updates a buildServer.json file with kind: xcode, instructing the server to watch and use compile flags from the newest Xcode build log.

Note: The directory where buildServer.json is created must be the root/working directory of your LSP.

Usage

Run one of the following commands in your workspace:

# For workspaces
xcode-build-server config -workspace *.xcworkspace -scheme <XXX>

# For projects
xcode-build-server config -project *.xcodeproj -scheme <XXX>

• *.xcworkspace or *.xcodeproj should be unique. If there is only one, you can omit these flags.
• -scheme <XXX> can be omitted to automatically bind the latest scheme build result.

If compile information becomes outdated, simply build your project in Xcode to refresh the flags.

Prerequisites

• Python 3.9 or newer (standard on recent macOS).

Installation Methods

Option 1: Homebrew (Recommended)

brew install xcode-build-server

Option 2: Macports

sudo port install xcode-build-server

Option 3: Manual Git Installation

Clone the repository and create a symbolic link to your bin folder:

git clone "https://github.com/SolaWing/xcode-build-server.git" && ln -s "$PWD"/xcode-build-server/xcode-build-server /usr/local/bin

The server uses a buildServer.json file in the project root to define its operating mode. The kind key determines how the server locates compiler information:

• xcode: The server automatically generates a unique compile file path based on the build_root (hashed) and the specified scheme. This isolates build information for different schemes.
• Manual: If the kind is not xcode, the server looks for a .compile file in the project root.

Other relevant configuration keys include build_root (the Xcode build directory) and scheme (the Xcode build scheme).

The server provides compiler arguments and working directory information to the LSP client (like sourcekit-lsp) through the textDocument_sourceKitOptions method. This allows the IDE to understand the build context for specific files.

When requested, the server:

1. Resolves the file path from the URI.
2. Retrieves flags from the .compile file using GetFlags.
3. If flags are missing for a .swift file, it attempts to infer them using InferFlagsForSwift.
4. Returns a JSON object containing compilerArguments and workingDirectory.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "compilerArguments": ["-isysroot", "/path/to/sdk", "-fmodules"],
    "workingDirectory": "/path/to/project"
  }
}

To ensure the server can notify the LSP when compiler flags change (e.g., after a new build), the client must register files using the textDocument_registerForChanges method.

• When the action is register, the URI is added to the observed_uri set.
• When the action is unregister, the URI is removed.

When the background thread detects a change in the .compile file, the server iterates through all observed_uri entries and sends a build/sourceKitOptionsChanged notification for any files whose flags may have changed.

The server_api() function acts as the primary entrypoint for the Build Server Protocol implementation. It returns a dictionary of functions (mapped from JSON-RPC methods) that the server dispatches to when receiving requests.

To implement or extend the server, you interact with the functions returned by server_api(). The dispatch mechanism converts JSON-RPC method names (e.g., build/shutdown) into Python function calls (e.g., build_shutdown).

# The server dispatches calls by replacing '/' with '_'
# Example: 'build/shutdown' calls 'build_shutdown(message)'
dispatch = server_api()

# Internal dispatch logic:
handler = dispatch.get(message["method"].replace("/", "_"))