Cameron Katri's Manual Page Server

Usage

To build an Xcode project, run xcodebuild from the directory containing your project (i.e. the directory containing the name.xcodeproj package). If you have multiple projects in the this directory you will need to use -project to indicate which project should be built. By default, xcodebuild builds the first target listed in the project, with the default build configuration. The order of the targets is a property of the project and is the same for all users of the project.

To build an Xcode workspace, you must pass both the -workspace and -scheme options to define the build. The parameters of the scheme will control which targets are built and how they are built, although you may pass other options to xcodebuild to override some parameters of the scheme.

There are also several options that display info about the installed version of Xcode or about projects or workspaces in the local directory, but which do not initiate an action. These include -list, -showBuildSettings, -showdestinations, -showsdks, -showTestPlans, -usage, and -version.

Options

-project name.xcodeproj

Build the project name.xcodeproj. Required if there are multiple project files in the same directory.

-target targetname

Build the target specified by targetname.

-alltargets

Build all the targets in the specified project.

-workspace name.xcworkspace

Build the workspace name.xcworkspace.

-scheme schemename

Build the scheme specified by schemename. Required if building a workspace.

-destination destinationspecifier

Use the destination device described by destinationspecifier. Defaults to a destination that is compatible with the selected scheme. See the Destinations section below for more details.

-destination-timeout timeout

Use the specified timeout when searching for a destination device. The default is 30 seconds.

-configuration configurationname

Use the build configuration specified by configurationname when building each target.

-arch architecture

Use the architecture specified by architecture when building each target.

-sdk [sdkfullpath | sdkname]

Build an Xcode project or workspace against the specified SDK, using build tools appropriate for that SDK. The argument may be an absolute path to an SDK, or the canonical name of an SDK.

-showsdks

Lists all available SDKs that Xcode knows about, including their canonical names suitable for use with -sdk. Does not initiate a build.

-showBuildSettings

Lists the build settings for targets in a project or workspace. Does not initiate a build. Use with -target or with -scheme. With -scheme, optionally pass a build action (such as build or test) to use targets from the matching scheme action.

-showdestinations

Lists the valid destinations for a project or workspace and scheme. Does not initiate a build. Use with -project or -workspace and -scheme.

-showBuildTimingSummary

Display a report of the timings of all the commands invoked during the build.

-showTestPlans

Lists the test plans (if any) associated with the specified scheme. Does not initiate a build. Use with -scheme.

-list

Lists the targets and configurations in a project, or the schemes in a workspace. Does not initiate a build. Use with -project or -workspace.

-enableAddressSanitizer [YES | NO]

Turns the address sanitizer on or off. This overrides the setting for the launch action of a scheme in a workspace.

-enableThreadSanitizer [YES | NO]

Turns the thread sanitizer on or off. This overrides the setting for the launch action of a scheme in a workspace.

-enableUndefinedBehaviorSanitizer [YES | NO]

Turns the undefined behavior sanitizer on or off. This overrides the setting for the launch action of a scheme in a workspace.

-enableCodeCoverage [YES | NO]

Turns code coverage on or off during testing. This overrides the setting for the test action of a scheme in a workspace.

-testLanguage language

Specifies ISO 639-1 language during testing. This overrides the setting for the test action of a scheme in a workspace.

-testRegion region

Specifies ISO 3166-1 region during testing. This overrides the setting for the test action of a scheme in a workspace.

-derivedDataPath path

Overrides the folder that should be used for derived data when performing an action on a scheme in a workspace.

-resultBundlePath path

Writes a bundle to the specified path with results from performing an action on a scheme in a workspace. If the path already exists, xcodebuild will exit with an error. Intermediate directories will be created automatically. The bundle contains build logs, code coverage reports, XML property lists with test results, screenshots and other attachments collected during testing, and various diagnostic logs.

-allowProvisioningUpdates

Allow xcodebuild to communicate with the Apple Developer website. For automatically signed targets, xcodebuild will create and update profiles, app IDs, and certificates. For manually signed targets, xcodebuild will download missing or updated provisioning profiles. Requires a developer account to have been added in Xcode's Accounts preference pane.

-allowProvisioningDeviceRegistration

Allow xcodebuild to register your destination device on the Apple Developer website if necessary. Requires -allowProvisioningUpdates.

-authenticationKeyPath

Specifies the path to an authentication key issued by App Store Connect. If specified, xcodebuild will authenticate with the Apple Developer website using this credential. Requires -authenticationKeyID and -authenticationKeyIssuerID.

-authenticationKeyID

Specifies the key identifier associated with the App Store Conect authentication key at -authenticationKeyPath. This string can be located in the users and access details for your provider at
⟨URL: https://appstoreconnect.apple.com ⟩

-authenticationKeyIssuerID

Specifies the App Store Connect issuer identifier associated with the authentication key at -authenticationKeyPath. This string can be located in the users and access details for your provider at
⟨URL: https://appstoreconnect.apple.com ⟩

-exportArchive

Specifies that an archive should be distributed. Requires -archivePath and -exportOptionsPlist. For exporting, -exportPath is also required. Cannot be passed along with an action.

-exportNotarizedApp

Export an archive that has been notarized by Apple. Requires -archivePath and -exportPath.

-archivePath xcarchivepath

Specifies the path for the archive produced by the archive action, or specifies the archive that should be exported when -exportArchive or -exportNotarizedApp is passed.

-exportPath destinationpath

Specifies the destination for the exported product, including the name of the exported file.

-exportOptionsPlist path

Specifies options for -exportArchive. xcodebuild -help can print the full set of available options.

-exportLocalizations

Exports localizations to XLIFF files. Requires -project and -localizationPath. Cannot be passed along with an action.

-importLocalizations

Imports localizations from an XLIFF file. Requires -project and -localizationPath. Cannot be passed along with an action.

-localizationPath

Specifies a path to a directory or a single XLIFF localization file.

-exportLanguage language

Specifies optional ISO 639-1 languages included in a localization export. May be repeated to specify multiple languages. May be excluded to specify an export includes only development language strings.

action ...

Specify one or more actions to perform. Available actions are:

build

Build the target in the build root (SYMROOT). This is the default action, and is used if no action is given.

build-for-testing

Build the target and associated tests in the build root (SYMROOT). This will also produce an xctestrun file in the build root. This requires specifying a scheme.

analyze

Build and analyze a target or scheme from the build root (SYMROOT). This requires specifying a scheme.

archive

Archive a scheme from the build root (SYMROOT). This requires specifying a scheme.

test

Test a scheme from the build root (SYMROOT). This requires specifying a scheme and optionally a destination.

test-without-building

Test compiled bundles. If a scheme is provided with -scheme then the command finds bundles in the build root (SRCROOT). If an xctestrun file is provided with -xctestrun then the command finds bundles at paths specified in the xctestrun file.

docbuild

Build the target and associated documentation in the build root (SRCROOT).

installsrc

Copy the source of the project to the source root (SRCROOT).

install

Build the target and install it into the target's installation directory in the distribution root (DSTROOT).

clean

Remove build products and intermediate files from the build root (SYMROOT).

-xcconfig filename

Load the build settings defined in filename when building all targets. These settings will override all other settings, including settings passed individually on the command line.

-testProductsPath path-to-xctestproducts

Specifies xctestproducts path. XCTestProducts are a unified test product format for XCTest. Can only be used with build-for-testing or test-without-building action. Cannot be used with -workspace or -project. When used with build-for-testing the path will be used as the destination for where the xctestproducts archive is written to. Example path: MyProject_MyScheme.xctestproducts When used with test-without-building the path will be used as the source of which xctestproducts archive to use for testing. test-without-building -testProductsPath Cannot be used with -workspace or -project.

-xctestrun xctestrunpath

Specifies test run parameters. Can only be used with the test-without-building action. Cannot be used with -workspace or -project. See
⟨URL: x-man-page://5/xcodebuild.xctestrun ⟩ for file format details.

-testPlan test-plan-name

Specifies which test plan associated with the scheme should be used for testing. Pass the name of the .xctestplan file without its extension.

-skip-testing test-identifier, -only-testing test-identifier

Constrain test targets, classes, or methods in test actions. -only-testing constrains a test action to only testing a specified identifier, and excluding all other identifiers. -skip-testing constrains a test action to skip testing a specified identifier, but including all other identifiers. Test identifiers have the form TestTarget[/TestClass[/TestMethod]]. The TestTarget component of an identifier is the name of a unit or UI testing bundle as shown in the Test Navigator. An xcodebuild command can combine multiple constraint options, but -only-testing has precedence over -skip-testing.

-skip-test-configuration test-configuration-name, -only-test-configuration test-configuration-name

Constrain test configurations in test actions. -only-test-configuration constrains a test action to only test a specified test configuration within a test plan, and exclude all other test configurations. -skip-test-configuration constrains a test action to skip a specified test configuration, but include all other test configurations. Each test configuration name must match the name of a configuration specified in a test plan and is case-sensitive. An xcodebuild command can combine multiple constraint options, but -only-test-configuration has precedence over -skip-test-configuration.

-disable-concurrent-destination-testing

Do not run tests on the specified destinations concurrently. The full test suite will run to completion on a given destination before it begins on the next.

-maximum-concurrent-test-device-destinations number

If multiple device destinations are specified (and -disable-concurrent-destination-testing is not passed), only test on number devices at a time. For example, if four iOS devices are specified, but number is 2, the full test suite will run on each device, but only two devices will be testing at a given time.

-maximum-concurrent-test-simulator-destinations number

If multiple simulator destinations are specified (and -disable-concurrent-destination-testing is not passed), only test on number simulators at a time. For example, if four iOS simulators are specified, but number is 2, the full test suite will run on each simulator, but only two simulators will be testing at a given time.

-parallel-testing-enabled [YES | NO]

Overrides the per-target setting in the scheme for running tests in parallel.

-parallel-testing-worker-count number

Spawn exactly number test runners when executing tests in parallel. Overrides -maximum-parallel-testing-workers, if it is specified.

-maximum-parallel-testing-workers number

Limit the number of test runners that will be spawned when running tests in parallel to number.

-parallelize-tests-among-destinations

If parallel testing is enabled (either via the -parallel-testing-enabled option, or on an individual test-target basis) and multiple destination specifiers are passed, distribute test classes among the destinations, instead of running the entire test suite on each destination (which is the default behavior when multiple destination specifiers are passed).

-test-timeouts-enabled [YES | NO]

Enable or disable test timeout behavior. This value takes precedence over the value specified in the test plan.

-default-test-execution-time-allowance seconds

The default execution time an individual test is given to execute, if test timeouts are enabled.

-maximum-test-execution-time-allowance seconds

The maximum execution time an individual test is given to execute, regardless of the test's preferred allowance.

-test-iterations number

If specified, tests will run number times. May be used in conjunction with either -retry-tests-on-failure or -run-tests-until-failure, in which case this will become the maximum number of iterations.

-retry-tests-on-failure

If specified, tests will retry on failure. May be used in conjunction with -test-iterations number, in which case number will be the maximum number of iterations. Otherwise, a maximum of 3 is assumed. May not be used with -run-tests-until-failure.

-run-tests-until-failure

If specified, tests will run until they fail. May be used in conjunction with -test-iterations number, in which case number will be the maximum number of iterations. Otherwise, a maximum of 100 is assumed. May not be used with -retry-tests-on-failure.

-test-repetition-relaunch-enabled [YES | NO]

Whether or not each repetition of test should use a new process for its execution. Must be used in conjunction with -test-iterations, -retry-tests-on-failure, or -run-tests-until-failure. If not specified, tests will repeat in the same process.

-collect-test-diagnostics [on-failure | never]

Whether or not verbose and long-running diagnostics, like sysdiagnoses or log archives, are collected when testing. If not specified, the value in the test plan will be used.

-enumerate-tests

If specified alongside either the test or test-without-building actions, the set of tests that would normally execute will instead be listed/enumerated, and the list of tests will be output to either stdout (the default), or to a file whose location is specified via the -test-enumeration-output-path option. The format of the list of tests is controlled via the -test-enumeration-style and -test-enumeration-format options. Note that a -destination specifier must be supplied in order to enumerate the tests.

-test-enumeration-style [hierarchical | flat]

Whether tests should be enumerated in a hierarchical organization (the default), meaning grouped by test plan, target, and class, or as a flat list of test identifiers that can subsequently be passed to the -skip-testing and -only-testing options.

-test-enumeration-format [text | json]

Whether tests should be enumerated as human-readable text (the default), or as machine-parseable JSON.

-test-enumeration-output-path [path | -]

Specifies a file path where the list of tests computed by the -enumerate-tests option will be written to disk. If - is supplied, the data will be written to stdout (which is also the default if this option is omitted).

-dry-run, -n

Print the commands that would be executed, but do not execute them.

-skipUnavailableActions

Skip actions that cannot be performed instead of failing. This option is only honored if -scheme is passed.

buildsetting=value

Set the build setting buildsetting to value.

A detailed reference of Xcode build settings can be found at:
⟨URL: https://developer.apple.com/documentation/xcode/build-settings-reference ⟩

-userdefault=value

Set the user default userdefault to value.

-toolchain [identifier | name]

Use a given toolchain, specified with either an identifier or name.

-quiet

Do not print any output except for warnings and errors.

-verbose

Provide additional status output.

-version

Display version information for this install of Xcode. Does not initiate a build. When used in conjunction with -sdk, the version of the specified SDK is displayed, or all SDKs if -sdk is given no argument. Additionally, a single line of the reported version information may be returned if infoitem is specified.

-license

Show the Xcode and SDK license agreements. Allows for accepting the license agreements without launching Xcode itself, which is useful for headless systems. Must be run as a privileged user.

-checkFirstLaunchStatus

Check if any additional system components or configuration tasks need to be performed. Exits with a non-zero code if additional system content needs to be installed, using -runFirstLaunch. Exits with 0 if system components are up-to-date.

-runFirstLaunch

Install additional system components and agree to the license.

-downloadAllPlatforms

Download and install all available platforms.

-usage

Displays usage information for xcodebuild.

Destinations

The -destination option takes as its argument a destination specifier describing the device (or devices) to use as a destination. A destination specifier is a single argument consisting of a set of comma-separated key=value pairs. The -destination option may be specified multiple times to cause xcodebuild to perform the specified action on multiple destinations.

Destination specifiers may include the platform key to specify one of the supported destination platforms. There are additional keys which should be supplied depending on the platform of the device you are selecting.

Some devices may take time to look up. The -destination-timeout option can be used to specify the amount of time to wait before a device is considered unavailable. If unspecified, the default timeout is 30 seconds.

Currently, xcodebuild supports these platforms:

macOS

The local Mac, referred to in the Xcode interface as My Mac, and which supports the following keys:

arch

The architecture to use, e.g. arm64 or x86_64.

variant

The optional variant to use, e.g. Mac Catalyst or macOS.

iOS

An iOS device, which supports the following keys:

id

The identifier of the device to use, as shown in the Devices window. A valid destination specifier must provide either id or name, but not both.

name

The name of the device to use. A valid destination specifier must provide either id or name, but not both.

iOS Simulator

A simulated iOS device, which supports the following keys:

id

The identifier of the simulated device to use, as shown in the Devices window. A valid destination specifier must provide either id or name, but not both.

name

The name of the simulated device to use. A valid destination specifier must provide either id or name, but not both.

OS

When specifying the simulated device by name, the iOS version for that simulated device, such as 6.0, or the string latest (the default) to indicate the most recent version of iOS supported by this version of Xcode.

watchOS

A watchOS app is always built and deployed nested inside of an iOS app. To use a watchOS device as your destination, specify a scheme which is configured to run a WatchKit app, and specify the iOS platform destination that is paired with the watchOS device you want to use.

watchOS Simulator

A watchOS Simulator app is always built and deployed nested inside of an iOS Simulator app. To use a watchOS Simulator device as your destination, specify a scheme which is configured to run a WatchKit app, and specify the iOS Simulator platform destination that is paired with the watchOS Simulator device you want to use.

tvOS

A tvOS device, which supports the following keys:

id

The identifier of the device to use, as shown in the Devices window. A valid destination specifier must provide either id or name, but not both.

name

The name of the device to use. A valid destination specifier must provide either id or name, but not both.

tvOS Simulator

A simulated tvOS device, which supports the following keys:

id

The identifier of the simulated device to use, as shown in the Devices window. A valid destination specifier must provide either id or name, but not both.

name

The name of the simulated device to use. A valid destination specifier must provide either id or name, but not both.

OS

When specifying the simulated device by name, the tvOS version for that simulated device, such as 9.0, or the string latest (the default) to indicate the most recent version of tvOS supported by this version of Xcode.

DriverKit

The DriverKit environment, which supports the following key:

arch

The architecture to use, e.g. arm64 or x86_64.

Some actions (such as building) may be performed without an actual device present. To build against a platform generically instead of a specific device, the destination specifier may be prefixed with the optional string "generic/", indicating that the platform should be targeted generically. An example of a generic destination is the "Any iOS Device" destination displayed in Xcode's UI when no physical iOS device is present.

Testing on Multiple Destinations

When more than one destination is specified with the -destination option, xcodebuild tests on those destinations concurrently. In this mode, xcodebuild automatically chooses the number of devices and simulators that are used simultaneously. All enabled tests in the scheme or xctestrun file are run on each destination.

Distributing Archives

The -exportArchive option specifies that xcodebuild should distribute the archive specified by -archivePath using the options specified by -exportOptionsPlist. xcodebuild -help can print the full set of available inputs to -exportOptionsPlist. The product can either be uploaded to Apple or exported locally. The exported product will be placed at the path specified by -exportPath.

Archives that have been uploaded to the Apple notary service can be distributed using the -exportNotarizedApp option. This specifies that xcodebuild should export a notarized app from the archive specified by -archivePath and place the exported product at the path specified by -exportPath. If the archive has not completed processing by the notary service, or processing failed, then xcodebuild will exit and emit informational or error messages.

When uploading an archive using the -exportArchive option, or exporting a notarized archive using the -exportNotarizedApp option, an Apple ID account belonging to the archive's development team is required. Enter the credentials for the Apple ID account using Xcode's Accounts preference pane before invoking xcodebuild.

Environment Variables

The following environment variables affect the execution of xcodebuild:

XCODE_XCCONFIG_FILE

Set to a path to a file, build settings in that file will be loaded and used when building all targets. These settings will override all other settings, including settings passed individually on the command line, and those in the file passed with the -xcconfig option.

TEST_RUNNER_<VAR>

Set an environment variable whose name is prefixed with TEST_RUNNER_ to have that variable passed, with its prefix stripped, to all test runner processes launched during a test action. For example, TEST_RUNNER_Foo=Bar xcodebuild test ... sets the environment variable Foo=Bar in the test runner's environment. Existing variables may be modified using the special token __CURRENT_VALUE__ to represent their current value. For example, TEST_RUNNER_Foo=__CURRENT_VALUE__:Bar appends the string :Bar to any existing value of Foo.

Exit Codes

xcodebuild exits with codes defined by sysexits(3). It will exit with EX_OK on success. On failure, it will commonly exit with EX_USAGE if any options appear malformed, EX_NOINPUT if any input files cannot be found, EX_IOERR if any files cannot be read or written, and EX_SOFTWARE if the commands given to xcodebuild fail. It may exit with other codes in less common scenarios.