XCODEBUILD(1) BSD General Commands Manual XCODEBUILD(1)NAMExcodebuild — build Xcode projects and workspaces
SYNOPSISxcodebuild [-project projectname] [-target targetname ...]
[-configuration configurationname]
[-sdk [sdkfullpath | sdkname]] [buildaction ...]
[setting=value ...] [-userdefault=value ...]
xcodebuild [-project projectname] -scheme schemename
[-destination destinationspecifier]
[-destination-timeout value]
[-configuration configurationname]
[-sdk [sdkfullpath | sdkname]] [buildaction ...]
[setting=value ...] [-userdefault=value ...]
xcodebuild-workspace workspacename -scheme schemename
[-destination destinationspecifier]
[-destination-timeout value]
[-configuration configurationname]
[-sdk [sdkfullpath | sdkname]] [buildaction ...]
[setting=value ...] [-userdefault=value ...]
xcodebuild-version [-sdk [sdkfullpath | sdkname]] [infoitem]
xcodebuild-showsdks
xcodebuild-list [-project projectname | -workspace workspacename]
xcodebuild-exportArchive -exportFormat format -archivePath xcarchivepath
-exportPath destinationpath
[-exportProvisioningProfile profilename]
[-exportSigningIdentity identityname]
[-exportInstallerIdentity identityname]
DESCRIPTIONxcodebuild builds one or more targets contained in an Xcode project, or
builds a scheme contained in an Xcode workspace or Xcode project.
Usage
To build an Xcode project, run xcodebuild from the directory containing
your project (i.e. the directory containing the projectname.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 parameters to display info about the installed
version of Xcode or about projects or workspaces in the local directory,
but which do not initiate a build. These include -version, -showsdks,
and -usage.
Options
-project projectname
Build the project specified by projectname. 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 workspacename
Build the workspace specified by workspacename.
-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 section on destinations 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.
-list
Lists the targets and configurations in a project, or the schemes
in a workspace. Does not initiate a build.
-derivedDataPath path
Overrides the folder that should be used for derived data when per‐
forming a build action on a scheme in a workspace.
-resultBundlePath path
Writes a bundle to the specified path with results from performing
a build action on a scheme in a workspace.
-exportArchive
Specifies that an archive should be exported. Requires
-exportFormat, -archivePath, and -exportPath. Cannot be passed
along with a build action.
-exportFormat format
Specifies the format to which the archive should be exported. Valid
formats are IPA (iOS archives only), PKG (Mac archives only), and
APP. If not specified, xcodebuild will attempt to auto-detect the
format as either IPA or PKG.
-archivePath xcarchivepath
Specifies the path for the archive produced by the archive action,
or specifies the archive that should be exported when
-exportArchive is passed.
-exportPath destinationpath
Specifies the destination for the exported product, including the
name of the exported file.
-exportProvisioningProfile profilename
Specifies the provisioning profile that should be used when export‐
ing the archive.
-exportSigningIdentity identityname
Specifies the application signing identity that should be used when
exporting the archive. If possible, this may be inferred from
-exportProvisioningProfile.
-exportInstallerIdentity identityname
Specifies the installer signing identity that should be used when
exporting the archive. If possible, this may be inferred from
-exportSigningIdentity or -exportProvisioningProfile.
-exportWithOriginalSigningIdentity
Specifies that the signing identity used to create the archive
should be used when exporting the archive.
buildaction ...
Specify a build action (or actions) to perform on the target.
Available build actions are:
build Build the target in the build root (SYMROOT). This is
the default build action.
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 destina‐
tion.
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 tar‐
gets. These settings will override all other settings, including
settings passed individually on the command line.
-dry-run, -n
Print the commands that would be executed, but do not execute them.
-skipUnavailableActions
Skip build actions that cannot be performed instead of failing.
This option is only honored if -scheme is passed.
setting=value
Set the build setting setting to value.
-userdefault=value
Set the user default default to value.
-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.
-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 destina‐
tion specifier is a single argument consisting of a set of comma-sepa‐
rated 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 con‐
sidered unavailable. If unspecified, the default timeout is 30 seconds.
Currently, xcodebuild supports these platforms:
OS X The local Mac, referred to in the Xcode interface as My
Mac, and which supports the following keys:
arch The architecture to use, either x86_64 (the default)
or i386.
iOS An iOS device, which supports the following keys:
name The name of the device to use.
id The identifier of the device to use, as shown in the
Devices tab of the Xcode Organizer.
iOS Simulator The iOS Simulator, which supports the following keys:
name The full name of device to simulate, as presented in
Xcode's UI.
OS The version of iOS to simulate, such as 6.0, or the
string latest (the default) to indicate the most
recent version of iOS supported by this version of
Xcode.
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 gener‐
ically. An example of a generic destination is the "iOS Device" destina‐
tion displayed in Xcode's UI when no physical iOS device is present.
Exporting Archives
The -exportArchive option specifies that xcodebuild should export the ar‐
chive specified by -archivePath to the format specified by -exportFormat.
The exported product will be placed at the path specified by -exportPath.
Re-signing when exporting an archive is optional. The provisioning profile
that should be embedded in the exported product can be specified by
-exportProvisioningProfile. In some cases, the application signing iden‐
tity that should be used during the export can be determined from the pro‐
visioning profile. For cases where that is not possible (including when no
provisioning profile is embedded in the exported product), an application
signing identity can be specified with -exportSigningIdentity. When
exporting a Mac archive as PKG, an installer signing identity can be used
to sign the exported package. This may be inferred from the application
signing identity (for instance, if "Developer ID Application" is specified
for the application signing identity, "Developer ID Installer" will auto‐
matically be inferred), but it can be explicitly specified using
-exportInstallerIdentity.
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 set‐
tings will override all other settings, including settings
passed individually on the command line, and those in the
file passed with the -xcconfig option.
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.
EXAMPLESxcodebuild clean install
Cleans the build directory; then builds and installs the first
target in the Xcode project in the directory from which
xcodebuild was started.
xcodebuild-target MyTarget OBJROOT=/Build/MyProj/Obj.root
SYMROOT=/Build/MyProj/Sym.root
Builds the target MyTarget in the Xcode project in the directory
from which xcodebuild was started, putting intermediate files in
the directory /Build/MyProj/Obj.root and the products of the
build in the directory /Build/MyProj/Sym.root.
xcodebuild-sdk macosx10.6
Builds the Xcode project in the directory from which xcodebuild
was started against the Mac OS X 10.6 SDK. The canonical names
of all available SDKs can be viewed using the -showsdks option.
xcodebuild-workspace MyWorkspace.xcworkspace -scheme MyScheme
Builds the scheme MyScheme in the Xcode workspace
MyWorkspace.xcworkspace.
xcodebuild-workspace MyWorkspace.xcworkspace -scheme MyScheme archive
Archives the scheme MyScheme in the Xcode workspace
MyWorkspace.xcworkspace.
xcodebuild-workspace MyWorkspace.xcworkspace -scheme MyScheme
-destination 'platform=OS X,arch=x86_64' test
Tests the scheme MyScheme in the Xcode workspace
MyWorkspace.xcworkspace using the destination described as My
Mac 64-bit in Xcode.
xcodebuild-workspace MyWorkspace.xcworkspace -scheme MyScheme
-destination 'platform=iOS Simulator,name=iPhone' -destination
'platform=iOS,name=My iPad' test
Tests the scheme MyScheme in the Xcode workspace
MyWorkspace.xcworkspace using both the iOS Simulator configured
as an iPhone and the the iOS device named My iPad. (Note that
the shell requires arguments to be quoted or otherwise escaped
if they contain spaces.)
xcodebuild-workspace MyWorkspace.xcworkspace -scheme MyScheme
-destination generic/platform=iOS build
Builds the scheme MyScheme in the Xcode workspace
MyWorkspace.xcworkspace using the generic iOS Device destina‐
tion.
xcodebuild-exportArchive -exportFormat IPA -archivePath
MyMobileApp.xcarchive -exportPath MyMobileApp.ipa
-exportProvisioningProfile 'MyMobileApp Distribution Profile'
Exports the archive MyMobileApp.xcarchive as an IPA file to the
path MyMobileApp.ipa using the provisioning profile MyMobileApp
Distribution Profile.
xcodebuild-exportArchive -exportFormat APP -archivePath
MyMacApp.xcarchive -exportPath MyMacApp.pkg
-exportSigningIdentity 'Developer ID Application: My Team'
Exports the archive MyMacApp.xcarchive as a PKG file to the path
MyMacApp.pkg using the application signing identity Developer ID
Application: My Team. The installer signing identity Developer
ID Installer: My Team is implicitly used to sign the exported
package.
SEE ALSOsysexits(3)Mac OS X January 22, 2013 Mac OS X
