Building Apple Platform Products

Building Apple Platform Products

Build, test, and archive Swift packages and Xcode projects for Apple platforms.

When to Use This Skill

Use this skill when you need to:

• Build an iOS, macOS, tvOS, watchOS, or visionOS app
• Build a Swift package
• Run unit tests or UI tests
• Create an archive for distribution
• Discover project structure (schemes, targets, configurations)

Tool Selection

Important: The swift build / swift test commands only work for standalone Swift packages. If a Swift package is embedded as a submodule within an Xcode project, you must use xcodebuild with the appropriate scheme—the Swift CLI cannot orchestrate builds in that context.

Project Discovery

Before building, discover the project structure:

# Find what project files exist
ls Package.swift *.xcworkspace *.xcodeproj 2>/​dev/​null

# List schemes and targets (auto-detects project)
xcodebuild -list

# Describe package (standalone SPM only)
swift package describe

Note: When an Xcode project references a local Swift package, each package target gets its own scheme (named after the target, not the package). Use these schemes to build individual targets without building the entire app.

For mixed projects, shared schemes, or detailed output parsing, see project-discovery.md.

Swift Package Manager Commands

Important: These commands only work for standalone Swift packages, not Swift Package Manager submodules in Xcode projects.

For cross-compilation, Package.swift syntax, or dependency management, see swift-package-manager.md.

xcodebuild Commands

Command structure: xcodebuild [action] -scheme <name> [-workspace|-project] [options] [BUILD_SETTING=value]

Required: -scheme is always required. Add -workspace or -project when multiple exist. For tests: -destination is required for iOS/​tvOS/​watchOS/​visionOS targets.

For build settings, SDK selection, or CI configuration, see xcodebuild-basics.md.

Common Destinations

Note: Simulator names change with each Xcode release. Always verify available simulators:

xcrun simctl list devices available

For all platforms, multiple destinations, or troubleshooting destination errors, see destinations.md.

Reference Files

Common Pitfalls

1. swift build with Xcode submodules: Only works for standalone packages. Use xcodebuild with the package's scheme instead.
2. Missing destination for iOS: Use -destination 'generic/​platform=iOS' for builds, or specify a simulator for tests.
3. Unnecessary workspace flag: Only use -workspace for CocoaPods or multi-project setups. Standard projects with SPM dependencies just use .xcodeproj.
4. Case-sensitive scheme names: Run xcodebuild -list to see exact scheme names.
5. Outdated simulator names: Names change with Xcode versions. Run xcrun simctl list devices available.
6. Code signing errors: Add CODE_SIGNING_ALLOWED=NO for builds that don't require signing.