Sailfish 构建加速快速入门

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 的域名。

1. 登录 持续交付控制台。

2. 在左侧导航栏选择 构建加速。

3. 在构建加速页面，单击 创建加速实例。

4. 在创建加速实例页面，选择 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 规模，为您推荐了合适的缓存实例个数。本示例保持默认。

   • 访问控制
     设置构建加速实例的访问控制策略。公网访问与私网访问请至少开启一个。本示例开启公网访问，关闭私网访问。

5. 在确认订单页面，确认构建加速实例配置和费用信息。

   • 确保待创建构建加速实例的相关配置符合预期，包括：配置详情、规格和计费类型。
   • 确认配置费用，包括：收费项、原价、折扣和折后价格。

6. 阅读 《持续交付产品服务条款》 并勾选同意，单击 立即购买，将完成购买操作，开始创建构建加速实例。

7. 完成以上操作后，构建加速实例处于 创建中 状态。创建时长受集群规模和镜像大小影响，通常为 10-20 分钟，请耐心等待。

8. 单击 去控制台，跳转至构建加速页面。查看创建的构建加速实例信息，状态为 运行中 表明创建成功。

步骤二：获取 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: AKLTZTYyYxxxxxxxxxxxxxxxxxxx
sk: Wrld2TENTxxxxxxxxxxxxxxxxxxx
# 指定集群访问地址
remote_executor: grpcs://<cluster_name>-<region>.buildcloud.volces.com
remote_cache: grpcs://<cluster_name>-<region>.buildcloud.volces.com
# 配置您的构建工程根目录
workspace：/abs_path/to/workspace
# 按需配置更多参数
# 使用项目自带的工具链场景下，需要将工具链发送到远端。例如：AOSP 会在代码仓库里集成自带的工具链，此时需要在配置文件中显示声明，将工具链发送到远端。
CompilerProxy：
  sendtoolchain: true

步骤四：开启构建加速

1. 启动 Sailfish 客户端

执行以下命令启动 Sailfish 客户端。该命令会根据配置好的工程目录以及远程构建地址，启动用于构建加速的多个客户端组件。默认在～/.sailfish文件夹下存储本次构建相关的配置和日志文件。

~/.sailfish/bin/SailfishClient start

2. 声明环境变量

声明环境变量，指向 Sailfish，用于截获构建系统下发的编译命令。

截获后，sailfish_wrapper 将在编译器路径前添加 sailfish_wrapper 路径，因此 sailfish_wrapper 中调用的编译命令形式如下:

/path/to/sailfish /path/to/clang -c hello.cc -o hello.o

下文为您介绍不同的构建系统如何声明环境变量。

• AOSP 构建系统

  # AOSP 构建系统需要声明以下环境变量:
  export CC_WRAPPER=~/.sailfish/bin/sailfish_wrapper
  export CXX_WRAPPER=~/.sailfish/bin/sailfish_wrapper
  
  # 禁用 Sailfish 时，需要取消环境变量：
  unset CC_WRAPPER
  unset CXX_WRAPPER
  

• CMake 构建系统

  # 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 build
  

• Xcode 构建系统

  # 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. 执行构建命令

执行您的构建命令开始构建加速。建议设置更高的本地构建并发度，有利于充分发挥云编译的资源优势。同时，远端构建实例的并发度推荐设置为本地核数的 3 ~ 5 倍，但注意不要超过构建实例的核数。

• AOSP 构建系统

source build/envsetup.sh && m -j 128

• CMake 构建系统

make -j 128

• Xcode 构建系统

xcodebuild ... --jobs 128

步骤五：关闭 Sailfish 客户端

在构建结束后，执行以下命令关闭构建加速客户端。

~/.sailfish/bin/SailfishClient stop

参数建议

Sailfish 客户端包括 CompilerProxy 和 RemoteProxy 两个组件，下文为您分别介绍两个组件的常用配置参数及取值建议。

CompilerProxy

1. Port
   Port 用于指定 CompilerProxy 的启动端口，默认 8088。

2. CacheOnly
   CacheOnly 用于开启纯分布式缓存模式，默认为 false。

3. DisableRemoteCache
   DisableRemoteCache 用于关闭远程缓存，默认为 false。关闭后，将禁用已有的远程编译缓存，但是允许本地继续上传编译产物。

4. DisableFileCache
   DisableFileCache 用于关闭 CompilerProxy 内部的文件状态缓存，默认为 false。

5. DisableDepsCache
   DisableDepsCache 用于关闭 CompilerProxy 内部的依赖解析缓存， 默认为 false。

6. DisableCompilerInfoCache
   DisableCompilerInfoCache 用于关闭工具链信息的缓存，默认为 false。

7. SendToolchain
   SendToolchain 用于开启编译工具链发送到远端的开关，默认为 false。

   注意

   使用 AOSP 构建系统，该参数需设置为 true。

8. CompilerPath
   CompilerPath 用于显示指定编译器路径。部分构建系统如 Xcode，由于环境变量 CC 的效果是直接替换编译器路径，会导致生成的 sailfish_wrapper 缺少编译器路径，无法正确截获编译命令。此时可设置该参数指定编译器路径，重新启动 SailfishClient，生成正确的 sailfish_wrapper。

RemoteProxy

1. Port
   Port 用于指定 RemoteProxy 的启动端口，默认为 8090。

2. FInfoCacheLevel
   FInfoCacheLevel 用于设置内部文件状态缓存的校验级别。该缓存会在计算编译缓存的 key 时，缓存已经计算过的文件内容 hash。

   • 0：禁用该缓存。
   • 1（默认）：仅检查 mtime。
   • 2：不对缓存进行校验。

   说明

   当您需要在构建期间修改文件内容时，建议禁用该缓存。

配置示例

下文举例说明如何定制化您的启动配置。当您希望发送工具链到远端，开启纯分布式缓存模式，并且指定 RemoteProxy 启动端口为 9000 时，配置形式如下：

$ cat ${HOME}/.sailfish/sailfish_conf.yaml
# 请替换您自己的 AK 和 SK。
# 请注意遵循 YAML规范，冒号后面需要空格。
ak: AKLTZTYyYxxxxxxxxxxxxxxxxxxx
sk: Wrld2TENTxxxxxxxxxxxxxxxxxxx
remote_executor: grpcs://<cluster_name>-<region>.buildcloud.volces.com
remote_cache: grpcs://<cluster_name>-<region>.buildcloud.volces.com

workspace：/abs_path/to/workspace

# 发送工具链到远端，开启纯分布式缓存模式，并且指定RemoteProxy 启动端口为 9000 
compilerproxy：
  sendtoolchain: true
  cacheonly: true
remoteproxy:
  port: 9000

使用示例

本节以开源仓库 AOSP 12 为例演示使用 Sailfish 的流程。

1. 获取 Sailfish 安装镜像。

   docker pull buildcloud-cn-shanghai.cr.volces.com/sailfish/sailfish-debian-bullseye:latest
   

2. 创建 Docker 环境。

   docker run -it buildcloud-cn-shanghai.cr.volces.com/sailfish/sailfish-debian-bullseye:latest bash
   

3. 修改本地配置。

   # 请参考上文步骤三完成。
   # AOSP 的配置需要发送工具链到远端，因此需要设置 sendtoolchain 为 true。
   vim ${HOME}/.sailfish/sailfish_conf.yaml
   

4. 安装 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
   

5. 下载 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
   

6. 开启构建加速。

   1. 启动 Sailfish 客户端。

   # 启动构建加速客户端。
    ~/.sailfish/bin/SailfishClient start
   

   2. 根据启动 SailfishClient 时的终端提示，以及您所使用的构建系统，声明相应的环境变量，实现对编译命令的截获。

   export CC_WRAPPER=/path/to/sailfish_wrapper
   export CXX_WRAPPER=/path/to/sailfish_wrapper
   

   3. 执行构建命令。

   source build/envsetup.sh
   m clean
   
   # 并发度建议设置为本地核数的3-5倍，不建议超过构建实例的核数。
   time m -j 112
   

7. 在构建结束后，执行以下命令关闭 Sailfish 客户端。

   ~/.sailfish/bin/SailfishClient stop
   unset CC_WRAPPER CXX_WRAPPER
   

常见问题

Sailfish 在开始编译前会使用配置文件中的 AK、SK，以及 remote urls 来获取远端构建集群信息，本节为您介绍可能的报错及解决办法。

1. check auth failed: invalid remote config

   • 可能原因：该报错表明 remote_executor/remote_cache 不是持续交付服务的官方 URL，此时无法正常从持续交付服务官方获取用于构建加速的 token，构建加速客户端无法正常启动。
   • 解决办法：
     • 如果您在用自定义地址进行调试，可直接忽略该错误，继续进行本地构建。
     • 如果您希望使用持续交付官方地址进行构建加速，请前往持续交付控制台构建加速页面，获取正确的 remote_executor/remote_cache 地址。

2. check auth failed: different names or regions in remote urls

   • 可能原因：remote_executor/remote_cache 分别指定了不同远端构建集群的 URL，编译失败退出。
   • 解决办法：请检查你的配置文件，确保传入的 remote_executor/remote_cache 地址来自同一个集群。

3. check auth failed: xxxxx

   • 可能原因：该报错表明获取集群鉴权信息失败，此时将无法成功启动 Sailfish，后续将只能进行本地构建。
   • 解决办法：
       请按照如下方法逐一排查。
     • 请前往持续交付控制台构建加速页面，检查集群状态是否为运行中。
     • 请检查 remote_executor/remote_cache 地址是否正确。正确地址格式为grpcs://<cluster_name>-<region>.``buildcloud.volces.com。
     • 请检查您使用的 AK 和 SK 是否正确有效。