Skip to content

Instantly share code, notes, and snippets.

@elfenlaid
Forked from mtauraso/xcodebuild flags.md
Created December 20, 2016 14:12
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save elfenlaid/58e664c37a7dc73b91e12e01f3b8a785 to your computer and use it in GitHub Desktop.
Save elfenlaid/58e664c37a7dc73b91e12e01f3b8a785 to your computer and use it in GitHub Desktop.
Xcodebuild flags in CI

Xcodebuild flag reference for CI:

Required flags:

-project OR -workspace

What xcode project/workspace file we're using. If you specify a project on the command-line and that project has an associated workspace, the project is still aware of its existence within the workspace. As an example, worspace level schemes will be available to xcodebuild even if you specify a project on the command line.

-scheme

Specify the scheme to use for build. Schemes specify multiple build/test targets along with environment args and command line parameters. Schemes must be marked "shared" in the xcode UI in order to be available to xcodebuild. For any particular build/test action there is a default configuration when you use a scheme from the Xcode UI.

-configuration

This needs to be specified on the command line even if the scheme specifies a default configuration. Why? There's a xcode-project-level config "Use config for command line builds" that overrides the config listed in the scheme when you use xcodebuild.

-destination="magic string"

Tells xcodebuild what platform + architecture we're building on. OSX, Simulator, real device. You can specify individual devices or simulators specifically with "id=UUID" syntax. See below

Example Destinations:

  • "id=UUID" Specify a particular simulator or device by UUID
  • "generic/platform=iOS" Build for a device
  • "platform=iOS Simulator,name=iPhone 5" Select a simulator automatically that has the given name.

ACTION: build, test, archive

What these do is set up in "Edit Scheme" inside of Xcode.app. Archive is special in that it uses stricter header + library search paths. Sometimes the library search paths are sloppy because a sub-project has SKIP_INSTALL set to "false". When "SKIP_INSTALL" is false, libraries are copied during the build action. This copying doesn't happen on archive action resulting in a failure to find the library.

Useful flags:

-resultBundlePath

Outputs a machine-readable xcodebuild log to the given directory. This is output as a plist and an older (pre xcode6) binary format.

-derivedDataPath

Set the derived data path to a known location. Useful for making sure its cleared when you expect.

-PBXBuildsContinueAfterErrors

Turn off xcode's default of continuing after errors to make logs more readable, and make it easier to find the failure that broke the build.

-showBuildSettings

Use in place of an action to dump all the environment-like variables that xcode uses for a build. Useful for testing the effect of particular flag combinations on xcodebuild.

-exportArchive

Run xcodebuild on a previously created .xcarchive file, does not accept other flags or take a workspace/project as a main object. It allows you to export a packaged application for iOS. Calling the packaging process this way allows your CI system to be decoupled from changes to the packaging format. Swift and Watch apps have so-far broken folks using the PackageApplication method.

Helpers

xcrun simctl

Lists simulators, also allows you to create and delete them. Useful to get the UUID for passing to the destination flag, and for creating blank simulators.

xcode-select

Use as root to select the active version of Xcode. xcrun and xcodebuild both respect the system-wide default.

Environment vars in xcodebuild

Environment variables in xcodebuild's environment are not passed through to xcode run-script actions. A default set is assembled from the system configuration as if you had started bash in Terminal.app.

An easy way to get environment variables into a run-script action is to pass them on the command line as project settings.

Corrections

This is a work in progress, that contains my current understanding of xcodebuild flags. Comments are welcome, especially if you have a reproduce case or experiment on a particular version of xcode that can pin down the behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment