You need to enable JavaScript to run this app.
导航
持续交付
  • 文档首页
    • /
  • 持续交付

Bazel 构建加速快速入门

最近更新时间：2024.02.28 17:25:06

首次发布时间：2023.05.06 10:39:33

我的收藏

Bazel 构建加速提供以 Bazel 生态为基础的远端构建执行和远端缓存服务，帮助企业成倍提升编译构建效率。本文为您介绍如何快速上手 Bazel 构建加速。

背景信息

购买构建加速实例后，持续交付会为您提供 remote-cache （远端缓存）和 remote-executor （远端构建执行）的域名。通过在构建命令中调用上述域名，即可调用远端构建集群执行编译构建任务，利用多机分布式编译和共享缓存能力，加速编译构建进程。

构建加速的使用流程如下图所示：
alt

前提条件

除 准备工作 外，您还需要完成以下操作：

  • 已准备好本地环境：支持使用 Docker 环境或 Linux 开发机。推荐您优先使用 Docker 环境，有利于保证本地环境和远端环境的一致性，提高远端编译构建成功率。

  • 已获取当前账号的访问密钥 AccessKey ID（AK）和 Secret Access Key（SK）。获取方式，请参见 访问密钥使用指南。

使用限制

  • 拥有 CPAdminAccess 权限的账号可以创建构建加速实例。火山引擎账号默认拥有持续交付产品的所有权限，可直接创建构建加速实例。子用户如需创建构建加速实例，请联系对应火山引擎账号授予该权限，具体操作请参考 创建子用户并授权。

  • 为了更好地进行权限管控，推荐使用火山引擎账号创建构建加速实例，使用子用户（赋予 CPMemberAccess 权限）的 AK/SK 做日常的编译开发。

操作步骤

步骤一：创建 Bazel 加速实例

创建一个构建加速实例，并获取 remote-cache 和 remote-executor 的域名。

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

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

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

  4. 在创建加速实例页面，选择 Bazel 类型，并按要求配置实例信息。完成后单击 确认订单。

    alt

    • 基本信息
    配置项说明
    名称自定义构建加速实例的名称。本示例为 bazel01。
    地域本示例选择 华北2（北京）。
    remote-cache展示远端缓存的域名。系统将根据您填写的实例名称（本示例为 bazel01）和地域信息，自动生成域名。
    remote-executor展示远端构建执行的域名。系统将根据您填写的实例名称（本示例为 bazel01）和地域信息，自动生成域名。
    构建镜像选择远端构建集群使用的容器镜像。本示例使用预置镜像。
    计费类型当前仅支持按量计费。
    • 构建实例规模
    配置项说明

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

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

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

步骤二：获取 Buildcloud 命令行工具

为了方便进行编译构建，持续交付为您提供了 Buildcloud 命令行工具。支持通过 Docker 镜像或二进制产物的方式获取。

  • （推荐）通过 Docker 镜像获取 Buildcloud 命令行工具

    推荐在本地使用 Docker 环境，有利于保证本地环境和远端环境的一致性，提高远端编译构建的成功率。

    说明

    Docker 镜像中预装了二进制产物 Buildcloud，本地环境可直接使用该 Docker 镜像，也可在您的镜像基础上安装 Buildcloud。

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

  • 通过二进制产物获取 Buildcloud 命令行工具
     方便在 Linux 开发机上直接调用远端构建集群。

    1. 执行以下命令安装 Buildcloud。
      curl -fsSL https://artifacts-cn-beijing.volces.com/repository/buildcloud-artifacts/buildcloud/scripts/install_buildcloud.sh | bash
    2. 执行以下命令查看 Buildcloud 版本，检验是否安装成功。
      buildcloud version

步骤三：修改本地配置

将您的火山引擎账号访问密钥 AK 和 SK 填入 Buildcloud 的配置文件${HOME}/.buildcloud/config.yaml 中，并保存。

$ cat ${HOME}/.buildcloud/config.yaml
# 请替换您自己的 AK 和 SK。
# 请注意遵循 YAML规范，冒号后面需要空格。
ak: AKLTZTYyYxxxxxxxxxxxxxxxxxxx
sk: Wrld2TENTxxxxxxxxxxxxxxxxxxx

步骤四：开启构建加速

只需在编译构建命令中指定以下两个地址，即可开启构建加速。

  • --remote_executor：指定远端构建执行地址。

  • --remote_cache：指定远端缓存地址。

具体命令如下：

# 请替换步骤一获取的 remote_executor 和 remote_cache 的 URL。
buildcloud build //... --remote_executor="grpcs://<cluster_name>-<region>.buildcloud.volces.com" --remote_cache="grpcs://<cluster_name>-<region>.buildcloud.volces.com"

说明

  • Buildcloud 兼容所有的 Bazel 原生参数。更进一步，可以在本地配置 alias bazel=buildcloud，从而继续使用 Bazel 命令，尽可能降低对用户代码的侵入性。
  • 为最大程度保证编译构建顺利执行， 当 Buildcloud 初始化失败时，默认仅打印 warning 并回滚到本地继续执行本次编译构建任务。您可通过 --fallthrough=false 参数强制关闭此功能，从而便于排查 Buildcloud 初始化失败的原因。

参数建议

介绍构建加速过程中常用的 Bazel 参数及取值建议。更多参数介绍请参见 Bazel 官方文档。

说明

如需指定以下参数，直接在编译构建命令中添加即可。

  1. --remote_executor 和 --remote_cache

    remote_executor 用于指定远端构建执行地址，remote_cache 用于指定远端缓存地址。

    • 支持同时指定 --remote_executor 和 --remote_cache 参数，同时开启远端构建执行和远端缓存能力。

    • 支持仅指定 --remote_cache 参数，单独开启远端缓存能力。此时，将在本地进行编译构建。

    • 不支持仅指定 --remote_executor 参数。仅指定 --remote_executor 可能会造成缓存问题，从而导致任务执行失败。

  2. --remote_local_fallback

    开启 remote_local_fallback，当任务在远端集群执行失败后，将回滚到本地重新执行，最大程度保证单次编译能够顺利执行完成。

    --remote_local_fallback=true

  3. --jobs

    该参数用于控制编译构建任务的并发数。当未配置该参数时，Bazel 默认选择本地 CPU 核数作为任务并发数，可能无法完全发挥出远端构建集群的加速能力。推荐将该参数设置为 50，并在集群端资源数量足够的情况下，逐步尝试增大此参数，直至达到最优加速效果。

    --jobs=50

  4. --disk_cache

    该参数用于指定本地缓存的路径。当指定路径不存在时，Bazel 会自动创建该路径。

    • 同时开启本地缓存和远端缓存后，Bazel 编译时会首先检查本地缓存，如果未命中缓存，则会进一步检查远端缓存，理论上可进一步加快编译速度。

    • 开启本地缓存可能会出现远端缓存和本地缓存不一致的情况，遇到此类问题时可尝试关闭该参数。

    --disk_cache=/path/to/local/cache/dir

  5. USE_BAZEL_VERSION

    Buildcloud 建立在 Bazelisk 和 Bazel 的基础上，编译时会实时拉取用户仓库中定义的 Bazel 特定版本。如果用户本地访问外网存在问题，拉取过程可能会失败，此时可以指定 Bazelisk 提供的 USE_BAZEL_VERSION 参数，强制使用本地预装的 Bazel。

    注意

    以上做法可暂时规避网络不通引起的拉取 Bazel 失败问题。如果编译过程中需要从外网拉取依赖，将同样面临网络问题，该情况推荐您优先解决网络问题。

    # USE_BAZEL_VERSION 必须设置为 Bazel 的具体路径。如果设置为版本号，Bazelisk 将从互联网中拉取 Bazel 对应版本，仍然会因为网络问题导致拉取失败。

export USE_BAZEL_VERSION=/path/to/bazel  # 例如 /usr/bin/bazel

使用示例

本节以开源仓库 abseil/abseil-cpp 为例演示使用 Buildcloud 的流程。

  1. 获取 Buildcloud 镜像。
docker pull buildcloud-cn-shanghai.cr.volces.com/buildcloud/buildcloud-debian-bullseye:latest
  1. 创建 Docker 环境。
docker run -it buildcloud-cn-shanghai.cr.volces.com/buildcloud/buildcloud-debian-bullseye:latest bash
  1. 安装必要软件。
apt-get update && apt-get install -y git vim build-essential
  1. 修改本地配置。
vim ${HOME}/.buildcloud/config.yaml  # 请参考上文相关内容填入火山账号 AK/SK，注意遵循 yaml 格式，冒号后面有一个空格
  1. （可选）预装 Bazel。
    如果没有网络代理，Buildcloud 将无法自动下载 Bazel。 此时，需要预装 Bazel，并强制 Buildcloud 调用本地 Bazel。如果已配置网络代理，可跳过当前步骤。
curl -fL https://artifacts-cn-beijing.volces.com/repository/buildcloud-artifacts/bazel/bin/bazel-6/bazel-6.1.2-linux-x86_64 -o /usr/local/bin/bazel
chmod +x /usr/local/bin/bazel

# 检查 bazel 是否安装成功
bazel version

# 强制 buildcloud 调用本地预装的 bazel
export USE_BAZEL_VERSION=/usr/local/bin/bazel
  1. 克隆 abseil/abseil-cpp 源码。
git clone https://github.com/abseil/abseil-cpp.git
  1. 开启分布式编译。
    请补全命令中 remote_executor 和 remote_cache 缺失的 cluster_name 和 region。
cd abseil-cpp
# 正常情况下执行下面的编译命令后即可顺利看到 bazel 日志
buildcloud build //... --jobs=100 --cxxopt='-std=c++14' --remote_executor="grpcs://<cluster_name>-<region>.buildcloud.volces.com" --remote_cache="grpcs://<cluster_name>-<region>.buildcloud.volces.com"

常见问题

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

  1. The remote urls are not valid buildcloud urls, pass them through

    • 可能原因：该报错表明 remote_executor/remote_cache 不是持续交付服务的官方 URL，此时会将打印该 warning，直接透传 remote urls 给 Bazel，编译将在您的自定义地址正常进行。
    • 解决办法：

      • 如果您在用自定义地址进行调试，可直接忽略该错误。

      • 如果您希望使用持续交付官方地址进行构建加速，请前往持续交付控制台构建加速页面，获取正确的 remote_executor/remote_cache 地址。

  2. The remote urls specify different names or regions

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

  3. Buildcloud initialization failed, fallthrough to local compile

    • 可能原因：该报错表明获取集群鉴权信息失败，此时将回滚至本地继续编译，如果设置了--fallthrough=false则会报错退出。
    • 解决办法：请按照如下方法逐一排查。
      • 请前往持续交付控制台构建加速页面，检查集群状态是否为运行中。
      • 请检查 remote_executor/remote_cache 地址是否正确。正确地址格式为grpcs://<cluster_name>-<region>.buildcloud.volces.com。
      • 请检查您使用的 AK 和 SK 是否正确有效。