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 ...

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

-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支持以下平台：

一些动作（比如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

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