---

name: xcb-config description: Configure xcb.json to map Xcode schemes to workspaces/projects for building with xcb

xcb Configuration Guide

xcb is a CLI wrapper around xcodebuild. The xcb.json file maps scheme names to their containers (workspace, project, or Swift package).

Config Structure

Copy{
  "version": 1,
  "open": {
    "defaultTarget": "app",
    "aliases": {
      "demo": "demo-app",
      "kit": "packages"
    }
  },
  "builds": [
    {
      "id": "optional-identifier",
      "scheme": "SchemeName",
      "workspace": "Path/To/App.xcworkspace",
      "destination": "platform=iOS Simulator,name=iPhone 15",
      "configuration": "Debug"
    }
  ]
}

Build Entry Fields

Open Shortcuts

If your repo has multiple Xcode containers, configure which one xcb open should use:

Copy{
  "open": {
    "defaultTarget": "app",
    "aliases": {
      "demo": "demo-app",
      "kit": "packages"
    }
  }
}

• open.defaultTarget points to a build entry by id (preferred) or by scheme.
• open.aliases maps short names to build entry id (or scheme).

Then:

Copyxcb open           # opens defaultTarget
xcb open demo      # opens aliases.demo

Common Destinations

• iOS Simulator: "platform=iOS Simulator,name=iPhone 15"
• Generic iOS: "generic/platform=iOS"
• macOS: "platform=macOS"
• watchOS Simulator: "platform=watchOS Simulator,name=Apple Watch Series 9 (45mm)"

How to Configure

1. Run xcb schemes to list available schemes from the workspace/project
2. For each scheme you want to build, add a build entry with:
   • The exact scheme name
   • The workspace or project path containing that scheme
   • Optional destination and configuration

Example: App with SPM Dependencies

Copy{
  "version": 1,
  "builds": [
    {
      "id": "app",
      "scheme": "MyApp",
      "workspace": "MyApp.xcworkspace",
      "destination": "platform=iOS Simulator,name=iPhone 15",
      "configuration": "Debug"
    },
    {
      "id": "tests",
      "scheme": "MyAppTests",
      "workspace": "MyApp.xcworkspace",
      "destination": "platform=iOS Simulator,name=iPhone 15",
      "configuration": "Debug"
    }
  ]
}

Example: Swift Package

Copy{
  "version": 1,
  "builds": [
    {
      "scheme": "MyLibrary",
      "packageDir": ".",
      "destination": "generic/platform=iOS"
    }
  ]
}

Example: Swift Package that Uses UIKit (macOS swift build will fail)

If any package targets import UIKit, do not rely on swift build on macOS. Use an iOS Simulator destination in xcb.json:

Copy{
  "version": 1,
  "builds": [
    {
      "id": "uikit-package",
      "scheme": "MyUIKitPackage",
      "packageDir": ".",
      "destination": "platform=iOS Simulator,name=iPhone 15",
      "configuration": "Debug"
    }
  ]
}

Notes:

• xcb will auto-generate a .xcodeproj for the package if needed.
• If you explicitly pass --destination or --sdk, those override defaults.

Usage After Configuration

Copyxcb MyApp          # Build the MyApp scheme
xcb MyAppTests     # Build the test scheme
xcb schemes        # List all available schemes