XCRemoteCache 是 Xcode 项目的远程缓存工具。它复用远程机器上生成的目标产物，这些产物通过一个简单的 REST 服务器提供。

• 如何以及为什么？
  • 精确的目标输入文件
    • 新文件添加到目标
  • 调试符号
  • 性能优化
  • 聚焦目标
• 如何将 XCRemoteCache 与您的 Xcode 项目集成？
  • 1. 下载 XCRemoteCache
  • A. 自动集成
    • 2. 创建一个最小化的 XCRemoteCache 配置
    • 3. 运行自动集成脚本
      • 3a. 生产者端
      • 3b. 消费者端
        • xcprepare integrate 支持的完整选项列表
  • B. 手动集成
    • 2. 配置 XCRemoteCache
    • 3. 调用 xcprepare
    • 4. 与 Xcode 项目集成
    • 5. 配置 LLDB 源映射（可选）
    • 6. 生产者模式 - 产物生成
      • 6a. 配置生产者模式
      • 6b. 填充缓存
      • 6c. 标记提交 sha
• 完整的配置参数列表
• 后端缓存服务器
  • 来自 Docker 镜像的示例 REST 缓存服务器
  • Amazon S3 和 Google Cloud Storage
• CocoaPods 插件
• 要求
• Apple Silicon 支持
  • 每个架构的产物（推荐）
  • 胖产物
• 局限性
• 常见问题解答
• 开发
• 架构设计
• 发布
  • 发布 CocoaPods 插件
  • 构建发布包
• 贡献
• 行为准则
• 许可证
• 安全问题？

缓存机制基于远程产物，这些产物应在 master 分支的每次提交时生成并上传到缓存服务器，最好作为 CI/CD 步骤的一部分。Xcode 产品在不同的 Xcode 版本之间不可移植，每个 XCRemoteCache 产物都与生成它的特定 Xcode 构建号相关联。为了支持多个 Xcode 版本，应为每个 Xcode 版本生成产物。

产物复用流程如下：XCRemoteCache 执行目标预检查（也称为预构建），如果本地源代码的指纹与生成端计算的指纹匹配，则几个编译步骤包装器（例如 xcswiftc、xccc、xclibtool）模拟相应的编译步骤，链接（或归档）操作将缓存的构建产物移动到预期位置。

具有相同目标源代码的多个提交在远程服务器上复用产物包。

找到精确的输入和依赖文件列表是一项非平凡的任务，因为 Xcode 严重依赖隐式目标依赖。这意味着 Xcode 尝试从提供的搜索路径中使用所需的依赖项，并在 DerivedData 的产品目录中查找。为了找到用于计算指纹哈希的狭窄文件列表，XCRemoteCache 从服务器获取 meta.json 文件，该文件包含远程生成的指纹哈希和构成指纹的输入文件列表。该输入文件列表是在产物生成过程中基于来自 clang 和 swift 编译器的 .d 输出生成的。

在 Xcode 中构建项目之前，XCRemoteCache 需要找到最佳的 git 提交 sha，以便使用其产物。这作为 xcprepare 执行的一部分发生，应在每次合并或切换分支后调用 xcprepare。xcprepare 使用 git 的 first-parent 策略查找与远程仓库分支的 10 个最新公共 sha 列表，并选择已上传所有产物的最新一个。

生成端负责在每次成功构建后调用 xcprepare mark 子命令。标记过程在远程缓存服务器上创建一个空标记文件，格式如下：#{commmmitSha}-#{TargetName}-#{Configuration}-#{Platform}-#{XcodeBuildNumber}-#{ContextBuildSettings}-#{SchemaID}.json。

xcprepare 对所有已识别的 sha 发出 HEAD 请求，选择远程存在标记文件的最新一个，并将其以文本形式保存到 arc.rc 文件中。该文件告知预构建阶段应获取哪个元文件以获取目标依赖文件列表。

如果在哈希指纹中仅考虑先前观察到的文件列表，则如果构建包含新的源文件，则可能会给出无效结果，因为它未在哈希中考虑。

对于仅 Swift 目标中的新 .swift 文件，xcswiftc 会自动识别这种情况，并强制对整个目标进行本地编译。对于 Objective-C 或混合目标，回退到本地编译更加困难，因为某些先前的调用（xccc 或 xcswiftc）可能已经完成，而没有操作。为了缓解这种情况，每个包装器将调用添加到侧文件 (history.compile)，以防其他进程需要本地编译整个目标。如果发生这种情况，新添加文件的编译将获得目标范围的锁，该锁会阻止其他包装器调用，逐个执行已模拟的步骤以回填已跳过的编译步骤。

使用“调试符号：已启用”构建的二进制文件嵌入了源文件绝对路径，因此编译产物不能在具有不同源根的两台机器之间直接移植。否则，LLDB 调试器无法将一组当前正在执行的机器指令与生成它的本地文件相关联。为了缓解这种情况，XCRemoteCache 建议为所有 XCRemoteCache 构建添加自定义 C 和 Swift 调试标志 prefix-map。这些标志确保本地生成和从远程服务器下载的所有二进制文件都具有相同的调试符号绝对路径，这些路径在 LLDB 会话开始时转换为实际的本地路径。

XCRemoteCache 涉及多种优化技术

• 本地 HTTP 缓存将来自远程服务器的所有响应存储在 ~/Library/Caches/XCRemoteCache/
• 预构建和后构建步骤利用 Xcode 发现的依赖文件，以避免在没有输入文件更改时重新计算指纹哈希
• clang 编译的包装器是一个 C 程序，在 xcprepare 步骤中生成和编译。它被多次调用以编译每个 *.(m|c) 文件，并且访问磁盘以读取配置会引入明显的减速，特别是如果项目包含大量 Objective-C 文件。作为补救措施，xcprepare 只读取一次 XCRemoteCache 配置，并将所有可配置字段直接嵌入到 xccc 二进制文件中
• 由 xcprepare 生成的 arc.rc 获取的文件修改日期等于其引用的提交日期。arc.rc 包含在发现的依赖文件中，在 xcprepare 中触摸它会自动使先前的 XCRemoteCache 预构建步骤无效，并强制执行冗余指纹检查。通过将 mdate 与 git 提交同步，Xcode 避免了预构建步骤，除非远程缓存提交已更改
• 如果发生目标缓存未命中，XCRemoteCache 会禁用该目标的缓存，直到 arc.rc 中的提交 sha 更改为止。这绕过了增量构建的指纹计算

如果可以具有脏源的目标列表是有限的，则可以使用在 .rcinfo 中指定的聚焦目标配置 XCRemoteCache。

默认情况下，所有目标都是聚焦目标，这些目标将本地指纹与远程可用的指纹进行比较，并在不匹配时回退到本地编译。非聚焦目标，称为“瘦”目标，始终使用缓存的产物，从而消除了指纹计算。“瘦”目标应仅包含具有 thin_target_mock_filename 的单个编译文件，例如 standin.swift 或 standin.m。

要在现有 .xcodeproj 中启用 XCRemoteCache，您需要向要缓存的目标添加额外的构建设置和构建阶段。

您可以使用 XCRemoteCache 提供的集成命令以自动方式执行此操作，或手动修改您的 Xcode 项目。

从 Github 发布页面，下载 XCRemoteCache 捆绑包 zip 文件。将捆绑包解压缩到 .xcodeproj 旁边的目录中。

以下步骤将假设捆绑包已解压缩到 xcremotecache 目录，放置在 .xcodeproj 旁边。

在 .xcodeproj 旁边创建 .rcinfo yaml 文件，其中包含最少的配置条目，例如

primary_repo: https://yourRepo.git
cache_addresses:
- https://xcremotecacheserver.com

执行修改 <yourProject.xcodeproj> 的命令

xcremotecache/xcprepare integrate --input <yourProject.xcodeproj> --mode producer --final-producer-target <YourMainTarget>

执行修改 <yourProject.xcodeproj> 的命令

xcremotecache/xcprepare integrate --input <yourProject.xcodeproj> --mode consumer

根据参数列表，在 .xcodeproj 旁边创建 yaml 配置文件 .rcinfo，其中包含您的完整 XCRemoteCache 配置，例如

primary_repo: https://yourRepo.git
cache_addresses:
 - https://xcremotecacheserver.com
repo_root: "."
remote_commit_file: arc.rc
xccc_file: xcremotecache/xccc

在每次与主分支合并或 rebase 后，执行 xcprepare --configuration #Configuration# --platform #platform# 命令。否则，远程缓存产物可能已过时，最终命中率可能会很差。

xcprepare 应用程序将 arc.rc 文件保存到磁盘，并将摘要打印到标准输出。打印的 recommended_remote_address 只是建议使用的缓存远程服务器。是否采用取决于集成工具的决定。如果采用，则项目的 .rcinfo 应将该值定义为 recommended_remote_address 参数。

示例

$ xcremotecache/xcprepare --configuration Debug --platform iphonesimulator
result: true
commit: aabbccc00
age: 0
recommended_remote_address: https://xcremotecacheserver.com

配置应使用 XCRemoteCache 的 Xcode 目标

1. 覆盖构建设置

• CC - 来自您的 .rcinfo 配置的 xccc_file（例如 xcremotecache/xccc）
• SWIFT_EXEC - xcprepare 的位置（例如 xcremotecache/xcswiftc）
• LIBTOOL - xclibtool 的位置（例如 xcremotecache/xclibtool）
• LIPO - xclipo 的位置（例如 xcremotecache/xclipo）
• LD - xcld 的位置（例如 xcremotecache/xcld）
• LDPLUSPLUS - xcldplusplus 的位置（例如 xcremotecache/xcldplusplus）
• XCRC_PLATFORM_PREFERRED_ARCH - $(LINK_FILE_LIST_$(CURRENT_VARIANT)_$(PLATFORM_PREFERRED_ARCH):dir:standardizepath:file:default=arm64)
• SWIFT_USE_INTEGRATED_DRIVER - NO（Xcode 14.0+ 中必需）

2. 添加一个 Prebuild 构建阶段（在编译之前）

• 命令："$SCRIPT_INPUT_FILE_0"
• 输入文件：xcprebuild 的位置（例如 xcremotecache/xcprebuild）
• 输出文件
  • $(TARGET_TEMP_DIR)/rc.enabled
  • $(DWARF_DSYM_FOLDER_PATH)/$(DWARF_DSYM_FILE_NAME)
• 发现依赖文件：$(TARGET_TEMP_DIR)/prebuild.d

3. 添加 Postbuild 构建阶段（在编译之后）

• 命令："$SCRIPT_INPUT_FILE_0"
• 输入文件：xcpostbuild 命令的位置（例如 xcremotecache/xcpostbuild）
• 输出文件
  • $(TARGET_BUILD_DIR)/$(MODULES_FOLDER_PATH)/$(PRODUCT_MODULE_NAME).swiftmodule/$(XCRC_PLATFORM_PREFERRED_ARCH).swiftmodule.md5
  • $(TARGET_BUILD_DIR)/$(MODULES_FOLDER_PATH)/$(PRODUCT_MODULE_NAME).swiftmodule/$(XCRC_PLATFORM_PREFERRED_ARCH)-$(LLVM_TARGET_TRIPLE_VENDOR)-$(SWIFT_PLATFORM_TARGET_PREFIX)$(LLVM_TARGET_TRIPLE_SUFFIX).swiftmodule.md5
• 发现依赖文件：$(TARGET_TEMP_DIR)/postbuild.d

重写源映射是支持调试和命中断点所必需的，请参阅调试符号。

1. 覆盖所有目标的以下构建设置

• XCRC_SRCROOT - /xxxxxxxxxx（或您的项目的任何其他任意字符串）
• 将 -debug-prefix-map $(SRCROOT)=$(XCRC_SRCROOT) 添加到 OTHER_SWIFT_FLAGS。如果它不存在，请将其定义为 $(inherited) -debug-prefix-map $(SRCROOT)=$(XCRC_SRCROOT)
• 将 -fdebug-prefix-map=$(SRCROOT)=$(XCRC_SRCROOT) 添加到 OTHER_CFLAGS。如果它不存在，请将其定义为 $(inherited) -fdebug-prefix-map=$(SRCROOT)=$(XCRC_SRCROOT)

2. 将 settings set target.source-map /xxxxxxxxxx /Users/account/src/PathToTheProject 添加到最终构建项目的机器上的 ~/.lldbinit

XCRC_SRCROOT 任意路径应该是项目独有的，以避免冲突。

提示：在极少数情况下，Xcode 会缓存 ~/.lldbinit 内容，因此请确保在修改后重新启动 Xcode。

XCRemoteCache 可以在两种主要模式下运行：consumer（默认）尝试复用远程服务器上可用的产物，而 producer 用于生成所有产物 - 它在本地构建所有目标并将元文件和产物文件上传到远程缓存服务器。

要启用 producer 模式，请直接在 .rcinfo 文件中配置它。

可选地，您可以在 .rcinfo 中定义 extra_configuration_file，其中包含指向另一个 yaml 文件的路径，该文件将覆盖 .rcinfo 中的默认配置。如果您想跟踪主 .rcinfo 并将本地配置保留在 git 之外，则此方法可能很有用。

从 Xcode 或使用 xcodebuild 构建项目

一旦所有产物都已上传，使用 xcprepare mark 命令“标记构建”

$ xcremotecache/xcprepare mark --configuration Debug --platform iphonesimulator

该命令在远程服务器上创建一个空文件，该文件告知对于给定的 sha、配置、平台、Xcode 版本等，所有产物都可用。

请注意，对于 producer 模式，预构建构建阶段和 xccc、xcld、xcldplusplus、xclibtool、xclipo 包装器变为无操作，因此建议不要为 producer 模式添加它们。

如果静态库目标包含混合目标，其桥接头文件在公共 Swift API 中公开来自 ObjC 的枚举，则将 *-Swift.h 移动到共享位置的自定义脚本也应将 *-Swift.h.md5 移动到其旁边。

示例

ditto "${SCRIPT_INPUT_FILE_0}" "${SCRIPT_OUTPUT_FILE_0}"

其中

• SCRIPT_INPUT_FILE_0="$(DERIVED_SOURCES_DIR)/$(SWIFT_OBJC_INTERFACE_HEADER_NAME)"
• SCRIPT_OUTPUT_FILE_0="$(BUILT_PRODUCTS_DIR)/include/$(PRODUCT_MODULE_NAME)/$(SWIFT_OBJC_INTERFACE_HEADER_NAME)"

ditto "${SCRIPT_INPUT_FILE_0}" "${SCRIPT_OUTPUT_FILE_0}"
[ -f "${SCRIPT_INPUT_FILE_1}" ] && ditto "${SCRIPT_INPUT_FILE_1}" "${SCRIPT_OUTPUT_FILE_1}" || rm -f "${SCRIPT_OUTPUT_FILE_1}"

其中

• SCRIPT_INPUT_FILE_0="$(DERIVED_SOURCES_DIR)/$(SWIFT_OBJC_INTERFACE_HEADER_NAME)"
• SCRIPT_INPUT_FILE_1="$(DERIVED_SOURCES_DIR)/$(SWIFT_OBJC_INTERFACE_HEADER_NAME).md5"
• SCRIPT_OUTPUT_FILE_0="$(BUILT_PRODUCTS_DIR)/include/$(PRODUCT_MODULE_NAME)/$(SWIFT_OBJC_INTERFACE_HEADER_NAME)"
• SCRIPT_OUTPUT_FILE_1="$(BUILT_PRODUCTS_DIR)/include/$(PRODUCT_MODULE_NAME)/$(SWIFT_OBJC_INTERFACE_HEADER_NAME).md5"

注意：如果以下至少一项为真，则不需要此步骤

• 您构建框架（而不是静态库）
• 您不通过桥接头文件将 NS_ENUM 类型从 ObjC 公开到 Swift

作为缓存服务器，XCRemoteCache 可以使用任何支持 PUT、GET 和 HEAD 方法的 REST 服务器。

在开发阶段，您可以尝试最简单的缓存服务器，该服务器在 backend-example 中以 Docker 镜像的形式提供。对于生产环境，建议配置可靠、快速的服务器，最好位于靠近开发人员机器的位置。

开箱即用，XCRemoteCache 支持 Amazon S3 和 Google GCS 使用的 V4 签名授权。或者，如果您的服务器具有自定义身份验证过程，则可以使用 request_custom_headers 配置属性添加额外的 HTTP 请求标头。

要运行服务器的本地实例，请使用一个代码片段，该代码片段在 https://:8080/cache 下公开缓存端点

docker build -t xcremotecache-demo-server backend-example
docker run -it --rm -d -p 8080:8080 --name xcremotecache xcremotecache-demo-server

由于 Docker 镜像将所有文件保存在容器的非持久性存储中，要重置缓存的内容，只需重新启动它

# stop the container
docker kill xcremotecache
# run a new instance of the image
docker run -it --rm -d -p 8080:8080 --name xcremotecache xcremotecache-demo-server

要查看缓存服务器中存储的所有文件，请导航到容器的缓存根目录

docker exec -w /tmp/cache -it xcremotecache /bin/bash

XCRemoteCache 支持使用 Amazon S3 和 Google Cloud Storage 存储桶作为缓存服务器，并使用 Amazon v4 签名授权。

要进行设置，请在 .rcinfo 文件中使用配置参数 aws_secret_key、aws_access_key、aws_region 和 aws_service。在同一文件中的 cache-addresses 字段中指定存储桶的 URL。

XCRemoteCache 还支持 AWS 临时访问密钥。将额外的 aws_security_token 参数与 aws_secret_key、aws_access_key 结合使用进行设置。此页面 描述了如何接收安全令牌。

示例

...
cache_addresses:
 - https://bucketname.s3.eu-central-1.amazonaws.com/
aws_secret_key: <SECRET_KEY>
aws_access_key: <ACCESS_KEY>
aws_region: eu-central-1
aws_service: s3
...

保留策略：存储桶通常具有保留策略选项，该选项确保对象保留一定的时间，并且不会被修改或删除。保持此选项较短或禁用它，以避免在生产者端为同一配置连续完成多个构建时出错。

前往我们的 cocoapods-plugin 文档，了解如何在您的 CocoaPods 项目中集成 XCRemoteCache。

如果您的所有机器（生产者和所有消费者都具有相同的架构，无论是 Intel 还是 Apple Silicon），则无需执行任何操作。

XCRemoteCache 支持为 Apple Silicon 消费者构建产物。建议为 x86_64 和 arm64 架构分别构建，以获得单架构产物，而无需下载不相关的二进制文件。如果您想同时支持 Intel 和 Apple Silicon 消费者，则需要执行以下步骤。

• 在生产者上为模拟器构建：首先为 x86_64 运行构建，清理构建并再次为 arm64 构建，例如

xcodebuild ARCHS=x86_64 ONLY_ACTIVE_ARCH=NO build ...
xcodebuild clean
xcodebuild ARCHS=arm64 ONLY_ACTIVE_ARCH=NO build ...

如果您希望生成胖产物（包含 Intel 和 Apple Silicon 二进制文件），则可以在生产者端禁用“仅构建归档架构”，例如

xcodebuild ONLY_ACTIVE_ARCH=NO build ...

注意：不建议使用此设置，并且未来的 XCRemoteCache 版本可能不支持此设置。

• git 版本控制下的仓库
• Xcode 11.4+
• Xcode New Build System
• 由 xcode-select 设置的当前 Xcode 位置
• 使用默认的 Xcode Toolchain
• 推荐：多目标 Xcode 项目
• 推荐：不要使用快进 PR 策略（请改用合并或 squash）
• 推荐：避免使用 DWARF with dSYM File “Debug Information Format” 构建设置。请改用 DWARF
• 推荐：避免在源根目录中包含符号链接（例如将项目放置在 /tmp 中）

• 不支持 Swift Package Manager (SPM) 依赖项。因为 SPM 不允许自定义构建设置，所以 XCRemoteCache 无法指定 clang 和 swiftc 包装器，这些包装器控制是否应跳过本地编译（缓存命中）或不跳过（缓存未命中）
• 带有 _vers.c 后缀的文件名是保留的，不能用作源文件
• 所有编译文件都应通过 git 仓库根目录引用。禁止引用解析到 git 仓库根目录之外的位置的 /AbsolutePath/someOther.swift 或 ../../someOther.swift。
• 新的 Swift 驱动程序（在 Xcode 14.0 中默认引入）不受支持，并且在使用 XCRemoteCache 时必须禁用

请关注 FAQ 页面。

请关注 Development 指南。它包含有关如何入门的所有信息。

请关注 架构设计 文档，其中描述和记录了 XCRemoteCache 的设计和实现细节。

要发布版本，请在 Releases 中草拟一个新版本，标签格式为 v0.3.0{-rc0}。带有二进制文件的软件包将自动上传到 GitHub Releases 页面。

增加在 gem_version.rb 中定义的 gem 版本，并创建上述新版本。

如果给定版本尚不存在，插件将自动上传到 RubyGems。

要为单个平台（例如 x86_64-apple-macosx、arm64-apple-macosx）构建发布 zip 包，请调用

rake 'build[release, x86_64-apple-macosx]'

zip 包将在 releases/XCRemoteCache.zip 中生成。

创建一个 新 issue，并尽可能提供详细信息。

我们认为一个友好的社区非常重要，我们要求您在与社区的所有互动中都遵守 Spotify 的 开源行为准则。

本项目遵守 开放行为准则。通过参与，您需要遵守此准则。

Copyright 2021 Spotify AB

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://apache.ac.cn/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

请通过 Spotify 的漏洞赏金计划 (https://hackerone.com/spotify) 而不是 GitHub 报告敏感的安全问题。