Sailfish 构建加速提供无侵入式构建加速能力，帮助企业在无需改造项目代码的情况下实现编译效率成倍提升。本文为您介绍如何快速上手 Sailfish 构建加速。
背景信息
Sailfish 构建加速提供基于 Sailfish 加速方案的无侵入式构建加速能力。通过截获编译命令，在本地完成高效的依赖文件解析，并创建编译请求、将其拆解分发至远端集群并发执行；结合增量编译、共享缓存等技术，成倍提升软件的编译构建效率。与 Bazel 构建加速相比，无需改造构建配置，对用户代码无侵入，上手门槛更低，适用于 C/C++/Objective-C 语言开发的项目。
Sailfish 构建加速的使用流程如下图所示：
前提条件
除 准备工作 外，您还需要完成以下操作：
已准备好本地环境：支持使用 Docker 环境或 Linux 开发机。推荐您优先使用 Docker 环境，有利于保证本地环境和远端环境的一致性，提高远端编译构建成功率。
已获取当前账号的访问密钥 AccessKey ID（AK）和 Secret Access Key（SK）。获取方式，请参见 访问密钥使用指南。
使用限制
权限
拥有 CPAdminAccess 权限的账号可以创建构建加速实例。火山引擎账号默认拥有持续交付产品的所有权限，可直接创建构建加速实例。子用户如需创建构建加速实例，请联系对应火山引擎账号授予该权限，具体操作请参考 创建子用户并授权。
为了更好地进行权限管控，推荐使用火山引擎账号创建构建加速实例，使用子用户（赋予 CPMemberAccess 权限）的 AK/SK 做日常的编译开发。
编程语言
支持 C/C++/Objective-C 等编程语言。工具链
主要指编译器以及编译器二进制依赖的一些库和资源文件。支持 clang 系列、gcc 系列、g++ 系列工具链。
不支持 MSVC 系列、高通系列 (需适配)、Intel C++、TCC、用户定制化工具链。
说明
远端集群已安装上述常用工具链。Sailfish 默认远端集群存在和本地相同的工具链，且位于相同的存储路径，无需额外配置。如果您使用的是项目自带的工具链，则需在 sailfish_conf.yaml 中开启 SendToolchain 配置，要求 Sailfish 将工具链及其依赖资源发送至远端集群。详情可参见下文 参数建议 章节的 SendToolchain 参数介绍。
如有额外工具链诉求，请 提交工单 寻求技术支持。
缓存正确性
除编译缓存外，Sailfish 组件内还包含系统缓存，用于提升计算编译缓存 key 的效率。使用系统缓存的前提是构建期间您的源文件内容保持不变，如果存在构建期间修改代码的需求，出于对编译正确性的考虑，建议您关闭下文 参数建议 章节提到的所有缓存。
操作步骤
步骤一：创建 Sailfish 加速实例
创建 Sailfish 加速实例，并获取 remote-cache 和 remote-executor 的域名。
登录 持续交付控制台。
在左侧导航栏选择 构建加速。
在构建加速页面，单击 创建加速实例。
在创建加速实例页面，选择 Sailfish 类型，并按要求配置实例信息。
基本信息
配置项 说明 名称 自定义构建加速实例的名称。本示例为 sailfish01。地域 本示例选择 华北2（北京）。 remote-cache 展示远端缓存的域名。系统将根据您填写的实例名称（本示例为 sailfish01）和地域信息，自动生成域名。remote-executor 展示远端构建执行的域名。系统将根据您填写的实例名称（本示例为 sailfish01）和地域信息，自动生成域名。构建镜像 选择远端构建集群使用的容器镜像。本示例使用预置镜像。 计费类型 当前仅支持按量计费。 构建实例规模
配置项 说明 CPU（Core）
选择构建实例的 CPU 规模，当前提供 64/128/256/512 Core 共 4 种选择。系统将根据您选择的 CPU 规格（Core），按照 1 ：2 的比例自动为您分配内存规格（GiB）。
说明
请根据您的构建任务并发规模选择合适的 CPU 核数。最大并发任务数 = 实例的 CPU 总核数 ，超过后需排队等待。例如： 本示例选择 64 Core CPU，则最多可并发执行 64 个构建任务，第 65 个任务将排队等待。
缓存资源
配置项 说明 数据盘（GiB） 展示单个缓存实例的数据盘大小，当前仅提供 1024 GiB 规格。 缓存实例数 设置缓存实例的个数。系统已根据您设置的 CPU 规模，为您推荐了合适的缓存实例个数。本示例保持默认。 访问控制
设置构建加速实例的访问控制策略。公网访问与私网访问请至少开启一个。本示例开启公网访问，关闭私网访问。
在确认订单页面，确认构建加速实例配置和费用信息。
- 确保待创建构建加速实例的相关配置符合预期，包括：配置详情、规格和计费类型。
- 确认配置费用，包括：收费项、原价、折扣和折后价格。
阅读 《持续交付产品服务条款》 并勾选同意，单击 立即购买，将完成购买操作，开始创建构建加速实例。
完成以上操作后，构建加速实例处于 创建中 状态。创建时长受集群规模和镜像大小影响，通常为 10-20 分钟，请耐心等待。
单击 去控制台，跳转至构建加速页面。查看创建的构建加速实例信息，状态为 运行中 表明创建成功。
步骤二：获取 Sailfish 客户端
为了方便进行无侵入式编译构建，持续交付为您提供了 Sailfish 客户端工具。支持通过 Docker 镜像或二进制产物的方式获取。
（推荐）通过 Docker 镜像获取 Sailfish 客户端工具
推荐在本地使用 Docker 环境，有利于保证本地环境和远端环境的一致性，提高远端编译构建的成功率。
说明
Docker 镜像中预装了 Sailfish 相关二进制，本地环境可直接使用该 Docker 镜像，也可在您的镜像基础上下载并安装 Sailfish 客户端。
docker pull buildcloud-cn-shanghai.cr.volces.com/sailfish/sailfish-debian-bullseye:latest通过二进制产物获取 Sailfish 客户端工具
方便在 Linux 开发机上直接调用远端构建集群。
执行以下命令安装 Sailfish。Sailfish 相关的工具会存储在
~/.sailfish/bin目录下。curl -fsSL https://artifacts-cn-beijing.volces.com/repository/buildcloud-artifacts/sailfish/scripts/install_sailfish.sh | bash执行以下命令查看 Sailfish 版本，检验是否安装成功。
~/.sailfish/bin/SailfishClient version
步骤三：修改本地配置
创建 Sailfish 的配置文件${HOME}/.sailfish/sailfish_conf.yaml ，填写以下配置并保存。
配置 AK/SK：推荐使用子用户（赋予 CPMemberAccess 权限）的 AK/SK。
指定集群访问地址：指定 remote_executor 和 remote_cache 的地址。
配置您的构建工程根目录。
按需配置更多参数： Sailfish 提供了更多高级参数，详细内容参考下文 参数建议 章节。
说明
如果这些高级参数保持默认值，则无需配置。
$ cat ${HOME}/.sailfish/sailfish_conf.yaml # 配置 AK/SK # 请替换您自己的 AK 和 SK。 # 请注意遵循 YAML规范，冒号后面需要空格。 ak: AKLTxxxxxxxxxxxxxxxxxxx sk: Wrldxxxxxxxxxxxxxxxxxxx # 指定集群访问地址 remote_executor: grpcs://<cluster_name>-<region>.buildcloud.volces.com remote_cache: grpcs://<cluster_name>-<region>.buildcloud.volces.com # 配置您的构建工程根目录 workspace：/abs_path/to/workspace # 按需配置更多参数 # 使用项目自带的工具链场景下，需要将工具链发送到远端。例如：AOSP 会在代码仓库里集成自带的工具链，此时需要在配置文件中显示声明，将工具链发送到远端。 sendtoolchain: true
步骤四：开启构建加速
启动 Sailfish 客户端
执行以下命令启动 Sailfish 客户端。该命令会根据配置好的工程目录以及远程构建地址，启动用于构建加速的多个客户端组件。默认在～/.sailfish文件夹下存储本次构建相关的配置和日志文件。
~/.sailfish/bin/SailfishClient start
声明环境变量
声明环境变量，指向 Sailfish，用于截获构建系统下发的编译命令。
注意
声明环境变量是开启 Sailfish 构建加速的关键步骤，否则构建加速能力无法生效。
截获后，sailfish_wrapper 将在编译器路径前添加 sailfish_wrapper 路径，因此 sailfish_wrapper 中调用的编译命令形式如下:
/path/to/sailfish /path/to/clang -c hello.cc -o hello.o
下文为您介绍不同的构建系统如何声明环境变量。
AOSP 构建系统（12 及以下）
# AOSP 构建系统（12 及以下）需要声明以下环境变量: export CC_WRAPPER=~/.sailfish/bin/sailfish_wrapper export CXX_WRAPPER=~/.sailfish/bin/sailfish_wrapper # 禁用 Sailfish 时，需要取消环境变量： unset CC_WRAPPER unset CXX_WRAPPERAOSP 构建系统（13 及以上）
# AOSP 构建系统（13 及以上）需要声明以下环境变量: export ANDROID_BUILD_ENVIRONMENT_CONFIG=rbe # 禁用 Sailfish 时，需要取消环境变量： unset ANDROID_BUILD_ENVIRONMENT_CONFIGCMake 构建系统
# CMake 构建系统需要声明以下环境变量: export CMAKE_C_COMPILER_LAUNCHER=~/.sailfish/bin/sailfish_wrapper export CMAKE_CXX_COMPILER_LAUNCHER=~/.sailfish/bin/sailfish_wrapper # 禁用Sailfish 时，需要取消环境变量，并删除产物的 build 文件夹，避免之前使用 Sailfish 时，CMake 生成的编译命令继续影响后续的构建。 unset CMAKE_C_COMPILER_LAUNCHER unset CMAKE_CXX_COMPILER_LAUNCHER rm -rf buildXcode 构建系统
# Xcode 构建系统需要声明以下环境变量: export CC=~/.sailfish/bin/sailfish_wrapper export CXX=~/.sailfish/bin/sailfish_wrapper # 禁用 Sailfish 时，需要取消环境变量： unset CC unset CXX注意
对于 Xcode 构建系统，CC/CXX 环境变量会完全替换编译器路径，而不是在编译器路径前添加 sailfish_wrapper 路径。因此，在 Xcode 环境下启动 Sailfish 时，需要通过 CompilerProxy 里的 CompilerPath 参数指定编译器路径（详情可参见下文 参数建议 章节的 CompilerPath 参数介绍），否则会导致 Xcode 生成的编译命令缺少实际的编译器路径。
执行构建命令
执行您的构建命令开始构建加速。建议设置更高的本地构建并发度，有利于充分发挥云编译的资源优势。同时，远端构建实例的并发度推荐设置为本地核数的 3 ~ 5 倍，但注意不要超过构建实例的核数。
- AOSP 构建系统
source build/envsetup.sh && m -j 128
- CMake 构建系统
make -j 128
- Xcode 构建系统
xcodebuild ... --jobs 128
步骤五：关闭 Sailfish 客户端
在构建结束后，执行以下命令关闭构建加速客户端。
~/.sailfish/bin/SailfishClient stop
参数建议
介绍构建加速过程中常用的配置参数及取值建议。
说明
若以下参数不使用默认配置，需要在 sailfish_conf.yaml 中指定参数的值，并重新启动 Sailfish 客户端。
- Workspace
待构建项目的工程根目录绝对路径。 - SkipCacheCheck
SkipCacheCheck 用于指定是否禁用编译缓存，默认为 false。测试仅开启分布式编译场景可开启该选项。 - UseRemoteExecutor
UseRemoteExecutor 用于指定是否开启远程集群的编译能力，默认为 true。测试仅开启分布式缓存场景可禁用该选项。 - SendToolchain
SendToolchain 用于开启编译工具链发送到远端的开关，默认为 false。AOSP 12 及以下版本构建需开启此选项。 - UseRBE
UseRBE 用于指定是否采用 RBE 方案，默认为 false。AOSP 13 及以上版本构建需开启此选项。
使用示例（AOSP 12及以下）
本节以开源仓库 AOSP 12 为例演示使用 Sailfish 的流程。
获取 Sailfish 安装镜像。
docker pull buildcloud-cn-shanghai.cr.volces.com/sailfish/sailfish-debian-bullseye:latest创建 Docker 环境。
docker run -it buildcloud-cn-shanghai.cr.volces.com/sailfish/sailfish-debian-bullseye:latest bash修改本地配置。
# 请参考上文步骤三完成 # vim ${HOME}/.sailfish/sailfish_conf.yaml ak: AKLTxxxxxxxxxxxxxxxxxxx sk: Wrldxxxxxxxxxxxxxxxxxxx remote_executor: grpcs://<cluster_name>-<region>.buildcloud.volces.com remote_cache: grpcs://<cluster_name>-<region>.buildcloud.volces.com workspace：/abs_path/to/workspace sendtoolchain: true安装 AOSP 12 的必要依赖。
# Install depends for ubuntu 18.04 # Also see https://source.android.google.cn/docs/setup/start/initializing?hl=zh-cn sudo apt-get install aptitude sudo aptitude install git repo gnupg flex bison build-essential zip curl zlib1g-dev libc6-dev-i386 libncurses5 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z1-dev libgl1-mesa-dev libxml2-utils xsltproc unzip fontconfig下载 AOSP 12 源码。
# Install repo cmd curl https://storage.googleapis.com/git-repo-downloads/repo > /usr/bin/repo chmod +x /usr/bin/repo # Config your git git config --global user.name YOURNAME git config --global user.email YOUREMAIL # AOSP 12 repo init -u https://mirrors.tuna.tsinghua.edu.cn/git/AOSP/platform/manifest -b android12L-release --repo-url=https://gerrit-googlesource.lug.ustc.edu.cn/git-repo repo sync -c -j96开启构建加速。
- 启动 Sailfish 客户端。
# 启动构建加速客户端。 ~/.sailfish/bin/SailfishClient start- 根据启动 SailfishClient 时的终端提示，以及您所使用的构建系统，声明相应的环境变量，实现对编译命令的截获。
export CC_WRAPPER=/path/to/sailfish_wrapper export CXX_WRAPPER=/path/to/sailfish_wrapper- 执行构建命令。
source build/envsetup.sh m clean # 并发度建议设置为本地核数的3-5倍，不建议超过构建实例的核数。 time m -j 112在构建结束后，执行以下命令关闭 Sailfish 客户端。
~/.sailfish/bin/SailfishClient stop unset CC_WRAPPER CXX_WRAPPER
使用示例（AOSP 13及以上）
本节以开源仓库 AOSP 13 为例演示使用 Sailfish 的流程。
获取 Sailfish 安装镜像。
docker pull buildcloud-cn-shanghai.cr.volces.com/sailfish/sailfish-debian-bullseye:latest创建 Docker 环境。
docker run -it buildcloud-cn-shanghai.cr.volces.com/sailfish/sailfish-debian-bullseye:latest bash修改本地配置。
# 请参考上文步骤三完成 # vim ${HOME}/.sailfish/sailfish_conf.yaml ak: AKLTxxxxxxxxxxxxxxxxxxx sk: Wrldxxxxxxxxxxxxxxxxxxx remote_executor: grpcs://<cluster_name>-<region>.buildcloud.volces.com remote_cache: grpcs://<cluster_name>-<region>.buildcloud.volces.com workspace：/abs_path/to/workspace UseRBE：true安装 AOSP 13 的必要依赖。
# Install depends for ubuntu 18.04 # Also see https://source.android.google.cn/docs/setup/start/initializing?hl=zh-cn sudo apt-get install aptitude sudo aptitude install git repo gnupg flex bison build-essential zip curl zlib1g-dev libc6-dev-i386 libncurses5 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z1-dev libgl1-mesa-dev libxml2-utils xsltproc unzip fontconfig下载 AOSP 13 源码。
# Install repo cmd curl https://storage.googleapis.com/git-repo-downloads/repo > /usr/bin/repo chmod +x /usr/bin/repo # Config your git git config --global user.name YOURNAME git config --global user.email YOUREMAIL # AOSP 13 repo init -u https://mirrors.tuna.tsinghua.edu.cn/git/AOSP/platform/manifest -b android-13.0.0_r43 --repo-url=https://gerrit-googlesource.lug.ustc.edu.cn/git-repo repo sync -c -j96开启构建加速。
- 启动 Sailfish 客户端。
# 启动构建加速客户端。 ~/.sailfish/bin/SailfishClient start- 根据启动 SailfishClient 时的终端提示，以及您所使用的构建系统，声明相应的环境变量，实现对编译命令的截获。
export ANDROID_BUILD_ENVIRONMENT_CONFIG=rbe- 执行构建命令。
source build/envsetup.sh m clean time m在构建结束后，执行以下命令关闭 Sailfish 客户端。
~/.sailfish/bin/SailfishClient stop unset ANDROID_BUILD_ENVIRONMENT_CONFIG
常见问题
Sailfish 在开始编译前会使用配置文件中的 AK、SK，以及 remote urls 来获取远端构建集群信息，本节为您介绍可能的报错及解决办法。
check auth failed: invalid remote config
- 可能原因：该报错表明 remote_executor/remote_cache 不是持续交付服务的官方 URL，此时无法正常从持续交付服务官方获取用于构建加速的 token，构建加速客户端无法正常启动。
- 解决办法：
- 如果您在用自定义地址进行调试，可直接忽略该错误，继续进行本地构建。
- 如果您希望使用持续交付官方地址进行构建加速，请前往持续交付控制台构建加速页面，获取正确的 remote_executor/remote_cache 地址。
check auth failed: different names or regions in remote urls
- 可能原因：remote_executor/remote_cache 分别指定了不同远端构建集群的 URL，编译失败退出。
- 解决办法：请检查你的配置文件，确保传入的 remote_executor/remote_cache 地址来自同一个集群。
check auth failed: xxxxx
- 可能原因：该报错表明获取集群鉴权信息失败，此时将无法成功启动 Sailfish，后续将只能进行本地构建。
- 解决办法：
请按照如下方法逐一排查。- 请前往持续交付控制台构建加速页面，检查集群状态是否为
运行中。 - 请检查 remote_executor/remote_cache 地址是否正确。正确地址格式为
grpcs://<cluster_name>-<region>.``buildcloud.volces.com。 - 请检查您使用的 AK 和 SK 是否正确有效。
- 请前往持续交付控制台构建加速页面，检查集群状态是否为