xcodebuild API

2017-03-01 本文已影响1357人许漠颜

XCODEBUILD通用命令指南

名字

xcodebuild
构建Xcode项目和工作空间

大纲

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 -list [-project name.xcodeproj | -workspace name.xcworkspace]

xcodebuild -exportArchive -archivePath xcarchivepath -exportPath destinationpath -exportOptionsPlist path

xcodebuild -exportLocalizations -project name.xcodeproj -localizationPath path
                [[-exportLanguage language] ...]

xcodebuild -importLocalizations -project name.xcodeproj -localizationPath path

描述

xcodebuild构建Xcode项目中的一个或者多个targets，或者一个Xcode项目或者一个Xcode工作空间的scheme。

用法

构建一个Xcode项目，从包含你项目的目录运行xcodebuild（这个目录包含包name.xcodeproj）。如果你有多个项目在这个目录你需要使用-project去表明你构建的是哪一个工程。默认情况下xcodebuild构建项目target列表中的第一个，并且使用默认的配置。这个规则对工程中的targets和所有工程的使用者是一样的。
构建一个xcode工作空间，你必须通过-workspace和-scheme定义这个构建。scheme参数控制哪一个targets被构建如何被构建，尽管你可以通过xcodebuild其他的选项推翻scheme的一些参数。
也有几个选项展示Xcode、工程、工作空间安装版本的信息在本地的目录中，但是无论哪一个都不能加入新的action。其中包含-list，-showBuildSettings，-showsdks，-usage，-version。

选项

-project name.xcodeproj

构建工程name.xcodeproj。要求多个工程在一个相同的目录下。

-target targetname

构建一个指定targetname的target

-alltargets

构建指定工程中所有的targets。

-workspace name.xcworkspace

构建一个名字为name.xcworkspace的工作空间。

-scheme schemename

通过schemename构建一个指定的scheme。这是必须的如果构建一个工作空间。

-destination destinationspecifier

使用destinationspecifier来描述destination设备。默认destination兼容选择的scheme。查看Destinations部分有更详细的信息。

-destination-timeout timeout

当搜索destination设备的时候使用指定的timeout。默认是30s。

-configuration configurationname

构建每个target的时候通过configurationname使用指定的构建配置。

-arch architecture

构建每个target的时候通过architecture使用一个指定的构建架构。

-sdk [sdkfullpath | sdkname]

构建一个Xcode工程或者工作空间不建议制定SDK，适当的使用SDK中的构建工具。这个参数可以是SDK的绝对路径，或者SDK的规范名称。

-showsdks

Xcode知道的所有的SDK的列表，包括他们适合使用的规范名称SDK。不能信加入一个构建。

-showBuildSettings

工程或者工作空间和scheme构建设置的列表。不能新加入一个构建。使用-project或者-workspace和-scheme。

-list

工程中targets和configurations的列表或者工作空间中schemes的列表。不能新加入一个构建。使用-project或者-workspace。

-enableAddressSanitizer [YES | NO]

转动address sanitizer开或者关。重载了工作空间中scheme launch action的设置。

-enableThreadSanitizer [YES | NO]

转动thread sanitizer开或者关。重载了工作空间中scheme launch action的设置。

-enableCodeCoverage [YES | NO]

测试的时候打开或者关闭代码覆盖。重写了工作空间scheme test action的设置。

-derivedDataPath path

当工作空间的scheme执行一个动作的时候重写文件夹用来导出数据。

-resultBundlePath path

写一个bundle到指定的路径同时工作空间下的scheme执行出了一个动作的结果。

-exportArchive

指定一个archive应该被输出。要求-archivePath，-exportPath和-exportOptionsPlist。不能和一个动作前行。

-archivePath xcarchivepath

archive动作之前为archive产品指定一个路径，或者当-exportArchive通过的时候指定一个archive输出。

-exportPath destinationpath

指定一个产品输出的目的地，包含输出文件的名字。

-exportOptionsPlist path

为-exportArchive指定选项。xcodebuild -help能够打印出来可获得的所有选项。

-exportLocalizations

出口本地化XLIFF文件。要求-project和-localizationPath。不能够和一个动作前行。

-importLocalizations

从XLIFF文件进口本地化，要求-project和-localizationPath。不能和一个动作前行。

-localizationPath

指定一个目录路径或者选出一个XLIFF文件。

-exportLanguage language

指定ISO 639-1语言选项包含在出口本地化中。可以重复的指定多种语言。可以排除一个指定的出口仅包含开发语言字符串。

action ...

指定一个或者多个动作执行。有效的动作包括:

build	构建一个target在build root（SYMROOT）。这是一个默认的动作，在没有动作的时候使用。
build-for-testing	构建target关联测试在build root（SYMROOT）。这也将生成一个xctestrun文件在build root。它要求指定一个scheme。
analyze	构建和分析一个target或者scheme在build root (SYMROOT)。它要求指定一个scheme。
archive	archive一个scheme从build root (SYMROOT)。它要求指定一个scheme。
test	测试一个scheme从build root (SYMROOT)。它要求指定一个scheme，（可选）选择一个目的地。
test-without-building	测试编译包。如果一个scheme伴随着-scheme提供然后命令发现bundles在build root (SRCROOT)。如果一个xctestrun文件伴随着-xctestrun然后命令发现在xctestrun文件中有指定的bundles路径。
install-src	复制工程资源到source root (SRCROOT)。
install	构建一个target安装它到target's安装目录在distribution root (DSTROOT)。
clean	移除一个构建产品和它里边的文件从build root (SYMROOT)。

-xcconfig filename

加载文件名定义中的构建设置当构建所有target的时候。这些设置将覆盖另外的所有设置，包含命令行种的个别设置。

-xctestrun xctestrunpath

指定测试运行参数。可以只被用于test-without-building动作。不能够用于-workspace和-project。看<x-man-page://5/xcodebuild.xctestrun>文件格式详细说明。

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

约束测试动作。-only-testing：约束一个测试动作只测试一个指定的标识，除掉其他所有的标识。-skip-testing：约束一个测试动作，跳过指定的测试标识，但是包含其他所有的标识。从TestTarget[/TestClass[/TestMethod]]得到测试标识。一个xcodebuild命令能够联合多个测试选项，但是-only-testing：优先级高于跳过。-skip-testing：.-dry-run, -n打印将要执行的命令，但是不要执行他们。

-skipUnavailableActions

跳过动作用不执行来代替失败。这个选项只能兑现如果-scheme通过。

buildsetting=value

设置一个构建设置buildsetting value。详细信息参考https://developer.apple.com/documentation/DeveloperTools/Reference/XcodeBuildSettingRef/。

-userdefault=value

设置用户默认userdefault value。

-toolchain [identifier | name]

使用给予的toolchain，指定identifier或者name。

-quiet

不打印任何输出处了警告和错误。

-verbose

提供附加的输出状态。

-version

展示安装的Xcode的版本信息。不能新添加一个构建。使用的时候结合-sdk，展示指定的SDK版本，或者所有SDK如果没有指定参数。此外，如果指定了infoitem会返回一行它的版本信息。

-license

展示Xcode和SDK许可协议。允许接受Xcode自己的许可协议在哪一个系统上都是有用的。必须运行一个有特权的用户。

Destinations

-destination选项作为destination说明符的一个参数描述destination设备（多个设备）。destination说明符是一个单独的参数由一组逗号分隔的key=value组成。-destination选项可以指定多次以使xcodebuild在多个destinations上指定指定的动作。
Destination说明符可以包含指定受支持的destination平台的平台键。根据你选择设备的平台提供额外的键。
一些设备可能需要时间去查找。-destination-timeout选项可以用于指定设备不可用之前的等待时间。如果未指定默认的超时时间是30s。
目前xcodebuild支持以下平台：

MacOS	本地Mac，在Xcode中称为My Mac，并且支持以下键：arch 架构的时候使用也支持x86_64（默认）或者i386。
iOS	一个iOS设备，支持以下键：id 要使用设备的标识，就像设备窗口中展示的那样。一个有效的destination说明符必须包括id或者name，但是不能同时提供两者。name 要使用设备的名字。一个有效的destination说明符必须包括id或者name，但是不能同时提供两者。
iOS Simulator	iOS设备的模拟器，支持一下键：id 要使用设备模拟器的标识，就像设备窗口中展示的那样。一个有效的destination说明符必须包括id或者name，但是不能同时提供两者。name 要使用设备模拟器的名字。一个有效的destination说明符必须包括id或者name，但是不能同时提供两者。OS 通过名称指定模拟器设备时，该模拟器设备的iOS版本（例如6.0）或string latest（默认）表示此版本是Xcode支持的最新版本的iOS。
watchOS Simulator	watchOS模拟器应用程序总是构建和部署嵌套在iOS模拟器应用程序中。要使用watchOS模拟器设备作为destination，请指定配置为运行WatchKit应用程序的方案，并指定与要使用的watchOS模拟器设备配对的iOS模拟器平台目标。
tvOS	一个tvOS设备，支持一下键：id 要使用设备的标识，就像设备窗口中展示的那样。一个有效的destination说明符必须包括id或者name，但是不能同时提供两者。name 要使用设备的名字。一个有效的destination说明符必须包括id或者name，但是不能同时提供两者。
tvOS Simulator	一个tvOS设备模拟器，支持一下键：id 要使用设备模拟器的标识，就像设备窗口中展示的那样。一个有效的destination说明符必须包括id或者name，但是不能同时提供两者。name 要使用设备模拟器的名字。一个有效的destination说明符必须包括id或者name，但是不能同时提供两者。OS 通过名称指定模拟器设备时，该模拟器设备的iOS版本（例如6.0）或string latest（默认）表示此版本是Xcode支持的最新版本的iOS。

一些动作（比如building）可以早没有实际设备的情况下运行。为了一般而不是针对特定设备平台构建，destination说明符可以用可选的字符串"generic/"作为前缀，表明该平台是一个一般的targeted。当没有物理iOS设备出现的时候，通用的destination示例在Xcode的UI中展示destination是"Generic iOS Device"。

Exporting Archives

-exportArchive选项指定xcodebuild应该使用由-exportOptionsPlist指定选项的-archivePath指定导出archive。xcodebuild -help能够打印全套可用的-exportOptionsPlist输出。导出的产品将放置到-exportPath指定的路径。

Environment Variables

以下的环境变量影响xcodebuild的执行：
XCODE_XCCONFIG_FILE 设置为文件路径，将在构建所有target时加载并使用该文件中的构建设置。这些设置将覆盖所有的其他设置，包括命令行中单独传递的设置以及通过-xcconfig选项传递的文件中的设置。

Exit Codes

xcodebuild退出时使用确定的代码sysexits(3)。EX_OK表示退出成功。失败的情况下，EX_USAGE表示任何一个选项格式显示不正确，EX_NOINPUT表示找不到任何输出文件，EX_IOERR表示任何文件无法读取或者写入，EX_SOFTWARE表示不常见错误情况。

EXAMPLES

xcodebuild clean install	清除build目录；然后在xcodebuild启动的目录中的Xcode工程中构建和安装第一个target。
xcodebuild -project MyProject.xcodeproj -target Target1 -target Target2 -configuration Debug	使用Debug配置在项目中构建target1和target2.
xcodebuild -target MyTarget OBJROOT=/Build/MyProj/Obj.root SYMROOT=/Build/MyProj/Sym.root	在xcodebuild启动的目录中的Xcode工程中构建target MyTarget，将中间的文件放在目录/Build/MyProj/Obj.root中并且把构建的产品放在目录/Build/MyProj/Sym.root中。
xcodebuild -sdk macosx10.6	在针对macOS 10.0 SDK启动xcodebuild的目录中构建Xcode项目。所有可用SDK的规范名称都可以使用-showsdks选项查看。
xcodebuild -workspace MyWorkspace.xcworkspace -scheme MyScheme	在Xcode工作空间MyWorkspace.xcworkspace中构建scheme MyScheme。
xcodebuild archive -workspace MyWorkspace.xcworkspace -scheme MyScheme	在Xcode工作空间MyWorkspace.xcworkspace中Archives scheme MyScheme。
xcodebuild build-for-testing -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination generic/platform=iOS	在Xcode工作空间MyWorkspace.xcworkspace使用通用的iOS设备destination构建测试和关联targets在scheme MyScheme。命令还将测试参数从scheme写入到构建产品目录中的xctestrun文件。
xcodebuild test-without-building -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=iOS Simulator,name=iPhone 5s' -destination 'platform=iOS,name=My iPad'	在Xcode工作空间MyWorkspace.xcworkspace中测试scheme MyScheme，使用模拟器iPhone 5s最新版本的iOS。这个命令假定测试包在构建根(SYMROOT)中。（如果shell包含空格，shell需要饮用参数或者转义）
xcodebuild test-without-building -xctestrun MyTestRun.xctestrun -destination 'platform=iOS Simulator,name=iPhone 5s' -destination 'platform=iOS,name=My iPad'	测试使用iOS模拟器并且设备名称是iPhone 5s。在MyTestRun.xctestrun指定测试包路径和其他的测试参数。这个命令需要项目二进制文件，不需要项目源代码。
xcodebuild test -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=macOS,arch=x86_64'	在Xcode工作空间MyWorkspace.xcworkspace中测试scheme MyScheme，使用Xcode中描述是64-bit的destination。
xcodebuild -exportArchive -archivePath MyMobileApp.xcarchive -exportPath ExportDestination -exportOptionsPlist 'export.plist'	使用export.plist中指定的选项将archive的MyMobileApp.xcarchive导出到路径ExportDestination。
xcodebuild -exportLocalizations -project MyProject.xcodeproj -localizationPath MyDirectory -exportLanguage zh-hans -exportLanguage es-MX	从MyProject.xcodeproj导出两个XLIFF文件到MyDirectory，包含简体中文和墨西哥西班牙语的开发语言和翻译。
xcodebuild -exportLocalizations -project MyProject.xcodeproj -localizationPath MyDirectory	从进包含开发语言的MyProject.xcodeproj将单个XLIFF文件导出到MyDirectory（这种情况下已经排除-exportLanguage参数）。
xcodebuild -importLocalizations -project MyProject.xcodeproj -localizationPath MyLocalizations.xliff	将本地化从MyLocalizations.xliff导出MyProject.xcodeproj。含有问题的翻译将会被报告，但是不会导入。

也可以查看
ibtool(1), sysexits(3), xcode-select(1), xcrun(1), xed(1)
Xcode Builds Settings Referencehttps://developer.apple.com/documentation/DeveloperTools/Reference/XcodeBuildSettingRef/