iOS自动构建工具 -- xcodebuild

工作项目中的iOS工程都是使用Shell脚本搭配xcodebuild自动构建而成，搭配Jenkins 持续集成（CI）工具，可以很方便的实现项目的构建、部署、自动化。

简介

xcodebuild是苹果发布自动构建的工具。它在一个Xcode项目下能构建一个或者多个targets,也能在一个workspace或者Xcode项目上构建scheme。

scheme 和 target的区别：
target包含了所有的源文件，它决定编译哪些文件。 一个project可以包含一个或多个target
scheme 定义了一个target的集合，它来决定和构建哪一个target

API介绍

Tips： 在终端输入man xcodebuild,可以查看xcdebuild详细的使用方法

文档描述如下：

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.

• 在包含xcodeproj的工程目录下执行xcodebuild命令可以编译该Xcode工程
• 如果该目录下包含多个xcode工程，xcodebuild命令需要指定 '-project'参数以指定编译的工程，默认xcodebuild命令会使用默认的编译配置编译工程中的第一个target
• target的顺序是由工程中的属性配置的，且该工程的所有用户的target一致

---

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.

• 构建一个workspace时，xcodebuild命令需要传递 '-workspace'参数和'-scheme'参数
• scheme中的参数会控制编译的target以及该target编译的方式，也可以使用xcodebuild命令传递的参数覆盖scheme中的参数

参数介绍

以下是xcodebuild命令的一些参数，其中有一些参数不会执行构建命令如：
-list,-showBuildSettings, -showdestinations
-showsdks, -showTestPlans, -usage, -version.

• -project name.xcodeproj
  编译工程 name.xcodeproj 该参数在当前目录有多个工程时必须存在
• -target targetname
  编译名叫 targetname 的target
• -alltargets
  编译指定工程的所有target
• -workspace name.xcworkspace
  编译名叫 name.xcworkspace 的workspace
• -scheme schemename
  编译名叫 schemename 的scheme 该参数在编译workspace时必须存在
• -destination destinationspecifer
  使用名为 destinationspecifer 的目标设备编译。默认目标设备与当前选择的scheme匹配。详情见 Destination section
• -configuration configurationname
  当编译target时，使用名为 configurationname 的编译配置进行编译
• -arch architecture
  当编译target时，使用名为 architecture 的架构进行编译
• -sdk [ sdkfullpath | sdkname ]
  使用指定的sdk编译 project或workspace, 该参数可以是SDK的绝对路径或SDK的简写名字

---

• -showsdks
  列出Xcode可用的SDK，包含他们的简写名。 该参数不会启动构建

• -showBuildSettings
  列出project workspace scheme的编译设置。 该参数不会启动构建 和 -project -workspace -scheme参数一起使用

• -showdestinations
  列出project workspace scheme的有效目标设备。 该参数不会启动构建 和 -project -workspace -scheme参数一起使用

• -showBuildTimingSummary
  显示编译所有命令的耗时报告

• -list
  列出project workspace scheme的target和配置项。 该参数不会启动构建 和 -project -workspace -scheme参数一起使用

• -derivedDataPath path
  重写编译的 DerivedData 目录
  ...
  ...

• action ...
  指示将要执行的若干action,可用的action如下：

action	expression
build	编译 build root（SYMROOT）下的target
Build-for-test	编译 build root（SYMROOT）下的target和相关的tests
analyze	编译 build root（SYMROOT）下的target并对该target静态分析
archive	打包 build root（SYMROOT）下的scheme,需要指定一个scheme
test	测试 build root（SYMROOT）下的scheme，需要制定一个scheme和可选目标设备
install	编译 target并安装到target的安装目录下（DSTROOT）
clean	移除 build root（SYMROOT）下的编译产物和生成文件

• -version
  打印Xcode的版本信息
• usage
  展示xcodebuild的通用信息

Destations -- 目标设备

-destination参数用于根据 destination specifier 指定特定的目标设备

当前，xcodebuild支持以下platforms

platforms	expression
macOS	The local Mac, referred to in the Xcode interface as My Mac
iOS	An iOS device
iOS Simulator	A simulated iOS device
watchOS	A watchOS app is always built and deployed nested inside of an iOS app.
watchOS Simulator	A watchOS Simulator app is always built and deployed nested inside of an iOS Simulator app.
tvOS	A tvOS device
tvOS Simulator	A simulated tvOS device

Testing on Mulitple Destinations

当使用 -destination参数指定大于一个目标设备时，xcodebuild 会并行在目标设备上执行测试。这个模式下，xcodebuild 自动同时的选择设备和模拟器的数目。所有可用的测试在每个目标设备上都会被执行

Distributing Archives -- 发布打包

参数 -exportArchive 指定了xcodebuild根据 -exportOptionPlist参数发布打包到 -archivePath路径下。product 可以上传到到Apple 或者导出到本地。 导出的product 会被放在 -exportPath路径下

Environment Variables

以下环境变量会影响xcodebuild的执行

XCODE_XCCONFIG_FILE 给一个文件设置一个路径，编译时该文件中的编译设置会被加载，该设置会覆盖所有其他设置

Exit Codes

xcodebuild 退出会返回 sysexit(3) 类型。
成功 EX_OK
参数错误 EX_USAGE
输入文件未找到 EX_NOINPUT
文件无法读写 EX_IOERR
命令执行失败 EX_SOFTWARE
其他场景可能会返回其他错误码

EXAMPLES -- 示例

• xcodebuild clean install
  clean 编译目录
  编译并安装project下的第一个target
• xcodebuild -project MyProject.xcodeproj -target Target1 -target Target2 -configuration Debug
  使用 Debug 的编译选项 编译 MyProject.xcodeproj 中的 Target1 和 Target2
• xcodebuild -target MyTarget OBJROOT=/Build/MyProj/Obj.root SYMROOT=/Build/MyProj/Sym.root
  编译 MyTarget
  中间文件放在 /Build/MyProj/Obj.root
  product 放在 /Build/MyProj/Sym.root
• xcodebuild -sdk macosx10.6
  基于macOS 10.6 编译xcodebuild 执行目录下的工程。可用的SDK简称可用通过 -showsdks 命令查看
• xcodebuild -workspace MyWorkspace.xcworkspace -scheme MyScheme
  编译 MyWorkspace.xcworkspace 下的 MyScheme
• xcodebuild archive -workspace MyWorkspace.xcworkspace -scheme MyScheme
  打包 MyWorkspace.xcworkspace 下的 MyScheme
• xcodebuild build-for-testing -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination generic/platform=iOS
  编译并运行 MyWorkspace.xcworkspace 下的 MyScheme 的测试,使用通用的iOS 目标设备。
• xcodebuild test -workspace MyWorkspace.xcworkspace -scheme MyScheme -destination 'platform=macOS,arch=x86_64' -only-testing MyTests/FooTests/testFooWithBar
  用指定的 64位macOS 测试scheme,只有 MyTests/FooTests/testFooWithBar 会被运行
• -exportArchive -archivePath MyMobileApp.xcarchive -exportPath ExportDestination -exportOptionsPlist 'export.plist'
  用指定的导出配置 export.plist 导出 MyMobileApp.xcarchive 到 ExportDestination 路径下