aiskillstore/using-xtool

Using xtool

Overview

xtool is a cross-platform Xcode replacement for building iOS apps with SwiftPM on Linux, Windows, and macOS. It is NOT XcodeGen, Tuist, or Xcode project files.

Critical: xtool is NOT XcodeGen

| xtool Uses | NOT These | |------------|-----------| | xtool.yml | project.yml, Project.swift | | Package.swift (SwiftPM) | Xcode project files | | xtool dev | xtool build, xtool run, xtool generate | | Sources/ directory | Extensions/ directory |

Project Structure

MyApp/
├── Package.swift          # SwiftPM package definition
├── xtool.yml              # xtool configuration
├── Sources/
│   ├── MyApp/             # Main app target
│   │   ├── MyAppApp.swift
│   │   └── ContentView.swift
│   └── MyWidget/          # Extension target (if any)
│       └── Widget.swift
├── MyApp-Info.plist       # Optional custom Info.plist
└── MyWidget-Info.plist    # Required for extensions

Quick Reference: Commands

# Project lifecycle
xtool new MyApp              # Create new project
xtool new MyApp --skip-setup # Create without running setup
xtool dev                    # Build + run (same as `xtool dev run`)
xtool dev build              # Build only
xtool dev build --ipa        # Build IPA file
xtool dev run -s             # Run on iOS Simulator (--simulator)
xtool dev run -c release     # Release build (--configuration)
xtool dev run -u <udid>      # Target specific device (--udid)
xtool dev generate-xcode-project  # Generate .xcodeproj for debugging

# Device management
xtool devices                # List connected devices
xtool install app.ipa        # Install IPA to device
xtool launch                 # Launch installed app
xtool uninstall              # Uninstall app from device

# Authentication & setup
xtool setup                  # Full setup (auth + SDK)
xtool auth login             # Authenticate with Apple
xtool auth status            # Check auth status
xtool auth logout            # Log out
xtool sdk                    # Manage Darwin Swift SDK

# Developer Services
xtool ds teams               # List development teams
xtool ds certificates        # Manage certificates
xtool ds profiles            # Manage provisioning profiles

xtool.yml Format

Minimal:

version: 1
bundleID: com.example.MyApp

Full options:

version: 1
bundleID: com.example.MyApp
product: MyApp                    # Which SwiftPM product is main app
infoPath: MyApp-Info.plist        # Custom Info.plist (merged)
iconPath: Resources/AppIcon.png   # App icon (1024x1024 PNG)
entitlementsPath: App.entitlements
resources:                        # Files copied to app bundle root
  - Resources/GoogleServices-Info.plist
extensions:                       # App extensions
  - product: MyWidget
    infoPath: MyWidget-Info.plist

Adding App Extensions (Widgets, Share, etc.)

Step 1: Update Package.swift

Add BOTH a product AND a target. Note: xtool uses .library (not .executable) - it bundles the library into an iOS app.

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "MyApp",
    platforms: [.iOS(.v17)],
    products: [
        .library(name: "MyApp", targets: ["MyApp"]),
        .library(name: "MyWidget", targets: ["MyWidget"]),  // ADD
    ],
    targets: [
        .target(name: "MyApp"),
        .target(name: "MyWidget"),  // ADD
    ]
)

Step 2: Update xtool.yml

version: 1
bundleID: com.example.MyApp
product: MyApp
extensions:
  - product: MyWidget
    infoPath: MyWidget-Info.plist

Step 3: Create Extension Info.plist

Minimal required (just the extension type):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSExtension</key>
    <dict>
        <key>NSExtensionPointIdentifier</key>
        <string>com.apple.widgetkit-extension</string>
    </dict>
</dict>
</plist>

Step 4: Create Extension Code

Sources/MyWidget/Widget.swift:

import WidgetKit
import SwiftUI

@main struct MyWidgetBundle: WidgetBundle {
    var body: some Widget { MyWidget() }
}

struct MyWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "MyWidget", provider: Provider()) { entry in
            Text(entry.date, style: .date)
                .containerBackground(.fill.tertiary, for: .widget)
        }
        .configurationDisplayName("My Widget")
    }
}

struct Entry: TimelineEntry { var date = Date() }

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> Entry { Entry() }
    func getSnapshot(in context: Context, completion: @escaping (Entry) -> Void) {
        completion(Entry())
    }
    func getTimeline(in context: Context, completion: @escaping (Entry) -> Void) {
        completion(Timeline(entries: [Entry()], policy: .after(.now + 3600)))
    }
}

Step 5: Build and Run

xtool dev

Common Extension Types

| Extension | NSExtensionPointIdentifier | |-----------|---------------------------| | Widget (WidgetKit) | com.apple.widgetkit-extension | | Share | com.apple.share-services | | Action | com.apple.ui-services | | Safari | com.apple.Safari.web-extension | | Keyboard | com.apple.keyboard-service | | Today (deprecated) | com.apple.widget-extension |

Troubleshooting

| Error | Solution | |-------|----------| | "Untrusted Developer" | Settings > General > VPN & Device Management > Trust | | Device not found | Connect USB, run xtool devices, enable Developer Mode | | Auth failed | Run xtool auth login | | Build fails on first run | Normal - SDK modules building. Wait for completion. |

Resources Configuration

SwiftPM resources (in bundle subdirectory):

.target(name: "MyApp", resources: [.copy("Blob.png")])
// Access: Image("Blob", bundle: Bundle.module)

Top-level resources (in app bundle root):

# xtool.yml
resources:
  - Resources/GoogleServices-Info.plist

Entitlements

# xtool.yml
entitlementsPath: App.entitlements

<!-- App.entitlements -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.homekit</key>
    <true/>
</dict>
</plist>

Common Mistakes

| Mistake | Fix | |---------|-----| | Using xtool build | Use xtool dev build | | Using project.yml | Use xtool.yml | | Using Extensions/ dir | Use Sources/ (standard SwiftPM) | | Forgetting Package.swift | Extensions need product + target in Package.swift | | Complex extension Info.plist | Only NSExtension/NSExtensionPointIdentifier required |