xcb-config

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

{
  "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

Field	Required	Description
scheme	Yes	Xcode scheme name (must match exactly)
workspace	One of these	Path to .xcworkspace file
project	required	Path to .xcodeproj file
packageDir		Path to Swift package directory
id	No	Identifier for the build entry
destination	No	xcodebuild destination string
configuration	No	Build configuration (Debug/Release)
sdk	No	SDK name (iphonesimulator, iphoneos, macosx)

Open Shortcuts

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

{
  "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:

xcb 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

{
  "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

{
  "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:

{
  "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

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