I’m running into some issues with the project setup Claude came up for me and I’m triaging it now. It’s using xcodebuild which prompted me to write this post.

Prerequisite

Highly recommend to acquaint yourself with the following definitions:

  • Project
  • Target
  • Scheme
  • Action
  • Destination
  • Product

For that see my stackoverflow answer to: Xcode: What is a target and scheme in plain language?

What is xcodebuild?

It’s command line tool made by Apple. It allows you to build, test, archive your app. It operates on one or more targets contained in your project, or a scheme contained in your project or workspace

Notes:
Your action is either: build, test, profile or archive.
Your operation is either defined through: a target or a scheme (which has associated targets).
Your operation is selected from either: a project or workspace.

Counter intuitively there is no support for running the app through xcodebuild. For that you’d have to use simctl to boot the sim, then install and launch the build into the sim. See here for more.

I’m guessing this is because:

A build is deterministic and stateless:

project + scheme + configuration + destination → build products

But “Run” is stateful and interactive, in addition to building it requires a destination, installs, launches, attaches a debugger and maintains a session.

This creates ambiguities around targets, debugging, diagnostics, and process handling all (while not impossible yet) difficult for a CLI to manage.

Why it’s more important to understand xcodebuild now?

  1. AI and agentic tools can build the same desired product through various permutations of target, scheme, configuration, platform, action and launch commands.
  2. When AI messes the piecing together of things, having a solid foundation to untangle things becomes critical.
  3. AI will mainly use xcodebuild cli to validate that it can build or that tests pass.
  4. For more see Building from the Command Line with Xcode FAQ

xcodebuild examples:

To build

xcodebuild -scheme <your_scheme_name> build

xcodebuild -scheme tvOS  build
=== BUILD TARGET tvOS OF PROJECT MyProject WITH CONFIGURATION Debug ===
...

To test

xcodebuild test [-workspace <your_workspace_name>]
                [-project <your_project_name>]
                -scheme <your_scheme_name>
                -destination <destination-specifier>
                [-only-testing:<test-identifier>]
                [-skip-testing:<test-identifier>]

xcodebuild defaults:

It’s worth noting, xcodebuild has a lot of defaults for:

  • Xcode version (set by xcode-select)
  • target (first target listed in the project)
  • action (build)
  • configuration (Debug)
  • destination. Note: The default only exists for the build action. For the test action you must specify the destination.

If you don’t specify them, then Xcode will just use the default or fail if the action you chose doesn’t have a default.

Test Execution Granularity

Agents frequently use xcodebuild test command to test an entire target, class or method.

# Do not test iOSAppUITests on an iPhone. Uses the `skip-testing` flag
xcodebuild test -workspace MyApplication.xcworkspace -scheme iOSApp -destination 'platform=iOS,name=iPhone' -skip-testing:iOSAppUITests

# Only testing SecondTestClass' testExampleB in the iOSAppTests unit test. Passes desired scope using the `YourTestTargetName[/TestClass[/TestMethod]]` format. 
xcodebuild test -workspace MyApplication.xcworkspace -scheme iOSApp -destination 'platform=iOS,name=iPhone' -only-testing:iOSAppTests/SecondTestClass/testExampleB

What else can be helpful to know how AI builds?

Knowing how the swift command works is also helpful.

swift build
swift test
swift test --filter ProfileRepositoryTests
swift package resolve
swift package update
swift package show-dependencies
swift package describe