1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939
| XCODEBUILD(1) BSD General Commands Manual XCODEBUILD(1)
NAME xcodebuild -- build Xcode projects and workspaces
SYNOPSIS xcodebuild [-project name.xcodeproj] [[-target targetname] ... | -alltargets] [-configuration configurationname] [-sdk [sdkfullpath | sdkname]] [action ...] [buildsetting=value ...] [-userdefault=value ...]
xcodebuild [-project name.xcodeproj] -scheme schemename [[-destination destinationspecifier] ...] [-destination-timeout value] [-configuration configurationname] [-sdk [sdkfullpath | sdkname]] [action ...] [buildsetting=value ...] [-userdefault=value ...]
xcodebuild -workspace name.xcworkspace -scheme schemename [[-destination destinationspecifier] ...] [-destination-timeout value] [-configuration configurationname] [-sdk [sdkfullpath | sdkname]] [action ...] [buildsetting=value ...] [-userdefault=value ...]
xcodebuild -version [-sdk [sdkfullpath | sdkname]] [infoitem]
xcodebuild -showsdks
xcodebuild -showBuildSettings [-project name.xcodeproj | [-workspace name.xcworkspace -scheme schemename]]
xcodebuild -showdestinations [-project name.xcodeproj | [-workspace name.xcworkspace -scheme schemename]]
xcodebuild -showTestPlans [-project name.xcodeproj | -workspace name.xcworkspace] -scheme schemename
xcodebuild -list [-project name.xcodeproj | -workspace name.xcworkspace]
xcodebuild -exportArchive -archivePath xcarchivepath -exportPath destinationpath -exportOptionsPlist path xcodebuild -exportNotarizedApp -archivePath xcarchivepath -exportPath destinationpath
xcodebuild -exportLocalizations -project name.xcodeproj -localizationPath path [[-exportLanguage language] ...] xcodebuild -importLocalizations -project name.xcodeproj -localizationPath path
DESCRIPTION xcodebuild 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 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 configu- ration. 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 over- ride 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 in a project or workspace and scheme. Does not initiate a build. Use with -project or -workspace and -scheme.
-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 col- lected 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.
-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 bun- dles at paths specified in the xctestrun file.
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.
-xctestrun xctestrunpath Specifies test run parameters. Can only be used with the test-without-building action. Cannot be used with -workspace or -project. See <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 spec- ified 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 com- bine 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 desti- nation 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.
-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: <https://help.apple.com/xcode/mac/current/#/itcaec37c2a6>
-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 First Launch tasks need to be performed.
-runFirstLaunch Install packages and agree to the license.
-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 destina- tion. 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 key:
arch The architecture to use, either x86_64 (the default) or i386.
variant The optional variant to use, e.g. Mac Catalyst.
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 des- tination, specify a scheme which is configured to run a WatchKit app, and specify the iOS platform destina- tion 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 ver- sion 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 generically. An example of a generic destination is the "Generic 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 spec- ifies 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.
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.
EXAMPLES xcodebuild 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 -project MyProject.xcodeproj -target Target1 -target Target2 -configuration Debug
Builds the targets Target1 and Target2 in the project MyProject.xcodeproj using the Debug configuration.
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 intermedi- ate 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 macOS 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 archive -workspace MyWorkspace.xcworkspace -scheme MyScheme
Archives the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace.
xcodebuild build-for-testing -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination generic/platform=iOS
Build tests and associated targets in the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace using the generic iOS device destination. The command also writes test parameters from the scheme to an xctestrun file in the built products directory.
xcodebuild test-without-building -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=iOS Simulator,name=iPhone 5s' -destination 'platform=iOS,name=My iPad'
Tests the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace using both the iOS Simulator and the device named iPhone 5s for the latest version of iOS. The command assumes the test bundles are in the build root (SYMROOT). (Note that the shell requires arguments to be quoted or otherwise escaped if they contain spaces.)
xcodebuild test-without-building -xctestrun MyTestRun.xctestrun -destination 'platform=iOS Simulator,name=iPhone 5s' -destination 'platform=iOS,name=My iPad'
Tests using both the iOS Simulator and the device named iPhone 5s. Test bundle paths and other test parameters are specified in MyTestRun.xctestrun. The command requires project binaries and does not require project source code.
xcodebuild test -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=macOS,arch=x86_64'
Tests the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace using the destination described as My Mac 64-bit in Xcode.
XCODEBUILD(1) BSD General Commands Manual XCODEBUILD(1)
NAME xcodebuild -- build Xcode projects and workspaces
SYNOPSIS xcodebuild [-project name.xcodeproj] [[-target targetname] ... | -alltargets] [-configuration configurationname] [-sdk [sdkfullpath | sdkname]] [action ...] [buildsetting=value ...] [-userdefault=value ...]
xcodebuild [-project name.xcodeproj] -scheme schemename [[-destination destinationspecifier] ...] [-destination-timeout value] [-configuration configurationname] [-sdk [sdkfullpath | sdkname]] [action ...] [buildsetting=value ...] [-userdefault=value ...]
xcodebuild -workspace name.xcworkspace -scheme schemename [[-destination destinationspecifier] ...] [-destination-timeout value] [-configuration configurationname] [-sdk [sdkfullpath | sdkname]] [action ...] [buildsetting=value ...] [-userdefault=value ...]
xcodebuild -version [-sdk [sdkfullpath | sdkname]] [infoitem]
xcodebuild -showsdks
xcodebuild -showBuildSettings [-project name.xcodeproj | [-workspace name.xcworkspace -scheme schemename]]
xcodebuild -showdestinations [-project name.xcodeproj | [-workspace name.xcworkspace -scheme schemename]]
xcodebuild -showTestPlans [-project name.xcodeproj | -workspace name.xcworkspace] -scheme schemename
xcodebuild -list [-project name.xcodeproj | -workspace name.xcworkspace]
xcodebuild -exportArchive -archivePath xcarchivepath -exportPath destinationpath -exportOptionsPlist path xcodebuild -exportNotarizedApp -archivePath xcarchivepath -exportPath destinationpath
xcodebuild -exportLocalizations -project name.xcodeproj -localizationPath path [[-exportLanguage language] ...] xcodebuild -importLocalizations -project name.xcodeproj -localizationPath path
DESCRIPTION xcodebuild 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 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 configu- ration. 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 over- ride 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 in a project or workspace and scheme. Does not initiate a build. Use with -project or -workspace and -scheme.
-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 col- lected 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.
-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 bun- dles at paths specified in the xctestrun file.
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.
-xctestrun xctestrunpath Specifies test run parameters. Can only be used with the test-without-building action. Cannot be used with -workspace or -project. See <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 spec- ified 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 com- bine 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 desti- nation 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.
-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: <https://help.apple.com/xcode/mac/current/#/itcaec37c2a6>
-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 First Launch tasks need to be performed.
-runFirstLaunch Install packages and agree to the license.
-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 destina- tion. 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 key:
arch The architecture to use, either x86_64 (the default) or i386.
variant The optional variant to use, e.g. Mac Catalyst.
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 des- tination, specify a scheme which is configured to run a WatchKit app, and specify the iOS platform destina- tion 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 ver- sion 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 generically. An example of a generic destination is the "Generic 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 spec- ifies 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.
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.
EXAMPLES xcodebuild 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 -project MyProject.xcodeproj -target Target1 -target Target2 -configuration Debug
Builds the targets Target1 and Target2 in the project MyProject.xcodeproj using the Debug configuration.
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 intermedi- ate 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 macOS 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 archive -workspace MyWorkspace.xcworkspace -scheme MyScheme
Archives the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace.
xcodebuild build-for-testing -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination generic/platform=iOS
Build tests and associated targets in the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace using the generic iOS device destination. The command also writes test parameters from the scheme to an xctestrun file in the built products directory.
xcodebuild test-without-building -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=iOS Simulator,name=iPhone 5s' -destination 'platform=iOS,name=My iPad'
Tests the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace using both the iOS Simulator and the device named iPhone 5s for the latest version of iOS. The command assumes the test bundles are in the build root (SYMROOT). (Note that the shell requires arguments to be quoted or otherwise escaped if they contain spaces.)
xcodebuild test-without-building -xctestrun MyTestRun.xctestrun -destination 'platform=iOS Simulator,name=iPhone 5s' -destination 'platform=iOS,name=My iPad'
Tests using both the iOS Simulator and the device named iPhone 5s. Test bundle paths and other test parameters are specified in MyTestRun.xctestrun. The command requires project binaries and does not require project source code.
xcodebuild test -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=macOS,arch=x86_64'
Tests the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace using the destination described as My Mac 64-bit in Xcode.
xcodebuild test -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=macOS,arch=x86_64' -only-testing MyTests/FooTests/testFooWithBar
Tests the scheme MyScheme in the Xcode workspace MyWorkspace.xcworkspace using the destination described as My Mac 64-bit in Xcode. Only the test testFooWithBar of the test suite FooTests, part of the MyTests testing bundle target, will be run.
xcodebuild -exportArchive -archivePath MyMobileApp.xcarchive -exportPath ExportDestination -exportOptionsPlist 'export.plist'
Exports the archive MyMobileApp.xcarchive to the path ExportDestination using the options specified in export.plist.
xcodebuild -exportLocalizations -project MyProject.xcodeproj -localizationPath MyDirectory -exportLanguage zh-hans -exportLanguage es-MX
Exports two XLIFF files to MyDirectory from MyProject.xcodeproj containing development language strings and transla- tions for Simplified Chinese and Mexican Spanish.
xcodebuild -exportLocalizations -project MyProject.xcodeproj -localizationPath MyDirectory
Export a single XLIFF file to MyDirectory from MyProject.xcodeproj containing only development language strings. (In this case, the -exportLanguage parameter has been excluded.)
xcodebuild -importLocalizations -project MyProject.xcodeproj -localizationPath MyLocalizations.xliff
Imports localizations from MyLocalizations.xliff into MyProject.xcodeproj. Translations with issues will be reported but not imported.
SEE ALSO ibtool(1), sysexits(3), xcode-select(1), xcrun(1), xed(1)
Xcode Builds Settings Reference <https://help.apple.com/xcode/mac/current/#/itcaec37c2a6>
macOS June 20, 2016 macOS (END)
|