如何将您的构建配置添加到 LLVM Buildbot 基础设施

简介

本文档包含关于向 LLVM Buildbot 基础设施添加构建配置和 Buildbot Worker 的信息。

注意

本文档中使用术语 “buildmaster” 来指代管理运行哪些构建以及在哪运行的服务器。尽管我们通常不会选择使用 “master” 术语，但在本文档中使用它是因为 Buildbot 包当前 使用 的术语。

Buildmasters

目前有两个 Buildmaster 在运行。

  • 主 Buildmaster 地址为 https://lab.llvm.org/buildbot。连接到此机器的所有构建器将在每次构建中断时通知提交作者。

  • 暂存 Buildmaster 地址为 https://lab.llvm.org/staging。连接到此机器的所有构建器在构建中断时默认情况下将完全静默。此 Buildmaster 每两小时使用来自 llvm-zorg 仓库的任何新提交重新配置。

为了保持与主 Buildmaster 的连接（并因此在失败时通知开发者），Buildbot 必须

  • 构建受支持的配置。实验性后端的构建器通常应连接到暂存 Buildmaster。

  • 能够跟上主分支的新提交，或者至少在落后几天内恢复到代码库顶端。

此外，我们鼓励所有 Bot 所有者在维护窗口、不稳定性故障排除等期间将其 Bot 指向暂存 master。

角色与期望

每个 Buildbot 都有一个所有者，他是负责解决所述 Buildbot 出现问题的责任方。我们通常期望 Bot 所有者能够做出合理的回应。

对于某些 Bot，所有权责任在提供底层机器资源的 “资源所有者” 和维护构建配置的 “配置所有者” 之间分配。通常，运营责任在于 “配置所有者”。我们确实期望 “资源所有者”（通常是在 Worker 属性中列出的联系人）及时将请求代理给相关的 “配置所有者”。

Buildbot 的大多数问题应直接通过电子邮件与 Bot 所有者联系解决。请抄送 Galina Kistanova。

向 LLVM Buildbot 添加构建器的步骤

志愿者可以提供他们的构建机器作为构建 Worker 以用于公共 LLVM Buildbot。

以下是可以遵循的步骤

  1. 检查现有的构建配置，以确保您感兴趣的配置尚未被覆盖，或者在您的计算机上构建速度比在现有计算机上快得多。我们更喜欢更快的构建，这样开发者将在更改提交后更快地获得反馈。

  2. 您将向 LLVM Buildbot 基础设施注册的计算机应安装所有依赖项，并且能够成功构建您的配置。请检查哪个程度的并行性（-j 参数）可以提供最快的构建速度。您可以在一台计算机上构建多个配置。

  3. 安装 buildbot-worker（目前我们正在使用 Buildbot 版本 2.8.4）。可以使用 pip 安装此特定版本，命令例如 pip3 install buildbot-worker==2.8.4。

  4. 创建一个指定的user帐户，您的 buildbot-worker 将在该帐户下运行，并设置适当的权限。

  5. 选择 buildbot-worker 根目录（所有构建都将放置在其下）、buildbot-worker 访问名称和密码，Build Master 将使用它们来验证您的 buildbot-worker 的身份。

  6. 在该 buildbot-worker 帐户的上下文中创建一个 buildbot-worker。将其指向 lab.llvm.org 端口 9994（请参阅 Buildbot 文档，创建 Worker 以获取更多详细信息），方法是运行以下命令

    $ buildbot-worker create-worker <buildbot-worker-root-directory> \
             lab.llvm.org:9994 \
             <buildbot-worker-access-name> \
             <buildbot-worker-access-password>

    只有在新 Worker 稳定并且收到 Galina 的批准（见最后一步）后，才应将其指向主 Buildmaster。

    现在启动 Worker

    $ buildbot-worker start <buildbot-worker-root-directory>

    这将导致您的新 Worker 连接到默认情况下处于静默状态的暂存 Buildmaster。

    尝试一次，然后检查日志文件 <buildbot-worker-root-directory>/worker/twistd.log。如果您的设置正确，您将看到连接被拒绝。这是好事并且是预期的，因为凭据尚未在两端建立。现在停止 Worker 并继续下一步。

  7. 填写 buildbot-worker 描述和管理员姓名/电子邮件。这是一个 buildbot-worker 描述的示例

    Windows 7 x64
Core i7 (2.66GHz), 16GB of RAM

g++.exe (TDM-1 mingw32) 4.4.0
GNU Binutils 2.19.1
cmake version 2.8.4
Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86

    有关要编辑的文件，请参阅 此处。

  8. 发送一个补丁，将您的构建 Worker 和您的构建器添加到 zorg。使用典型的 LLVM 工作流程。

    • Worker 被添加到 buildbot/osuosl/master/config/workers.py

    • 构建器被添加到 buildbot/osuosl/master/config/builders.py

    请确保您的构建器名称及其 builddir 在文件中是唯一的。

    所有新的构建器应默认使用 “‘collapseRequests’: False” 配置。这会导致构建器单独构建每个提交，而不是合并构建请求。为了最大限度地提高对开发者的反馈质量，我们强烈建议将构建器配置为不折叠请求。只有在已尽一切合理努力来缩短构建时间，以便构建器能够跟上提交流程之后，才应删除此标志。

    可以允许电子邮件地址无条件地接收构建失败的通知；为此，您需要在 buildbot/osuosl/master/config/status.py 中添加一个 InformativeMailNotifier。这对于默认情况下处于静默状态的暂存 Buildmaster 尤其有用。

  9. 将 buildbot-worker 访问名称和访问密码直接发送给 Galina Kistanova，并等待她通知您您的更改已应用并且 Buildmaster 已重新配置。

  10. 确保您可以启动 buildbot-worker 并成功连接到静默 Buildmaster。然后设置您的 buildbot-worker 在启动时自动启动。有关帮助，请参阅 Buildbot 文档。您可能需要重启计算机以查看它是否有效。

  11. 在 瀑布显示 (暂存) 上检查您的 buildbot-worker 的状态，以确保它已连接，并在 Worker 显示 (暂存) 上查看管理员联系方式和 Worker 信息是否正确。

  12. 此时，您已拥有一个连接到暂存 Buildmaster 的工作构建器。现在您可以确保它可靠地保持绿色状态并跟上构建队列。不会发送通知，因此您可以将不稳定的构建器无限期地连接到暂存环境。

  13. （可选）一旦构建器在暂存 Buildmaster 上稳定运行并有几天的绿色历史记录，您可以选择将其移动到生产 Buildmaster 以启用开发者通知。请发送电子邮件给 Galina Kistanova 以进行审查和批准。

    要将 Worker 移动到生产环境（获得批准后），请停止您的 Worker，编辑 buildbot.tac 文件以将端口号从 9994 更改为 9990，然后再次启动它。

在本地测试构建器配置

可以针对 LLVM Buildmaster 设置的本地版本测试正在运行的构建器。这允许您测试对构建器、Worker 和 Buildmaster 配置的更改。在此 “本地测试” 模式下启动的 Buildmaster 将

  • 仅绑定到本地接口。

  • 使用 SQLite 作为数据库。

  • 为 Worker 使用单个固定密码。

  • 禁用 GitHub 身份验证等附加功能。

为了使用此 “本地测试” 模式

  • 创建并激活 Python venv 并安装必要的依赖项。此步骤可以从任何目录运行。

    python -m venv bbenv
source bbenv/bin/activate
pip install buildbot{,-console-view,-grid-view,-waterfall-view,-worker,-www}==3.11.7 urllib3

  • 如果您的系统具有 Python 3.13 或更高版本，您将需要额外安装 legacy-cgi 并对已安装的 Buildbot 包进行小的修补。对于早期版本的 Python，不需要遵循此步骤。

    pip install legacy-cgi
sed -i \
  -e 's/import pipes/import shlex/' \
  -e 's/pipes\.quote/shlex.quote/' \
  bbenv/lib/python3.13/site-packages/buildbot_worker/runprocess.py

  • 初始化必要的 Buildmaster 文件，链接到 llvm-zorg 本地检出中的配置，并要求 buildbot 检查配置。此步骤可以从任何目录运行。

    buildbot create-master llvm-testbbmaster
cd llvm-testbbmaster
ln -s /path/to/checkout/of/llvm-zorg/buildbot/osuosl/master/master.cfg .
ln -s /path/to/checkout/of/llvm-zorg/buildbot/osuosl/master/config/ .
ln -s /path/to/checkout/of/llvm-zorg/zorg/ .
BUILDBOT_TEST=1 buildbot checkconfig

  • 启动 Buildmaster。

    BUILDBOT_TEST=1 buildbot start --nodaemon .

  • 等待几秒钟以完成启动后，您应该可以在 https://127.0.0.1:8011 打开 Web UI。如果出现任何错误或无法正常工作，请检查 twistd.log（在当前目录中）以获取更多信息。

  • 您现在可以创建并启动 Buildbot Worker。确保为您要测试的构建配置选择正确的 Worker 名称，该名称在 buildbot/osuosl/master/config/builders.py 中。

    buildbot-worker create-worker <buildbot-worker-root-directory> \
                localhost:9990 \
                <buildbot-worker-name> \
                test
buildbot-worker start --nodaemon <buildbot-worker-root-directory>

  • 等待轮询器启动构建，或者在 Web UI 中强制启动构建。

  • 在 Web UI 中查看构建的进度和结果。

出于安全原因，此本地测试配置默认为仅绑定到环回接口。

如果您想在不同的机器上运行测试 Worker，或者在远程服务器上运行 Buildmaster，则可以使用 SSH 端口转发使连接成为可能。例如，如果在远程服务器上运行 Buildmaster，以下命令将足以使 Web UI 可以通过 https://127.0.0.1:8011 访问，并使本地 Worker 可以通过连接到 localhost:9900 连接到远程 Buildmaster

ssh -N -L 8011:localhost:8011 -L 9990:localhost:9990 username@buildmaster_server_address

请注意，某些构建配置可能会检出当前的 upstream llvm-zorg 仓库，以便检索构建过程中使用的其他脚本，这意味着任何本地更改都不会反映在构建的这一部分中。如果您希望在不将其提交到上游的情况下测试对这些脚本的更改，则需要临时修补构建器逻辑，以便改为检出您自己的分支。通常，zorg/buildbot/process/factory.py 中的 addGetSourcecodeForProject 用于此目的，您可以编辑调用者以指定您自己的 repourl 和/或 branch 关键字参数。

配置快速构建器的最佳实践

如上所述，我们通常强烈偏好能够构建每个传入提交的构建器。本节包含最佳实践和关于如何实现此目标的建议。

目标

在 2020 年，单体仓库有略低于 3.5 万次提交。这相当于平均每小时 4 次提交。我们已经可以看到，构建器必须在不到 15 分钟的时间内完成一个周期才能有望发挥作用。但是，这些提交并非均匀分布。它们在美国工作时间往往会强烈聚集。查看最近几天（2021 年 11 月）的工作日，我们经常看到在高峰时段每小时约 10 次提交，偶尔高峰高达每小时约 15 次提交。因此，作为经验法则，我们应该计划我们的构建器每小时完成约 10-15 次构建。

合理分配资源

以每小时 10-15 次构建的速度，我们需要平均每 4 到 6 分钟完成一次新构建。对于除最快的硬件/构建配置之外的任何情况，这都将远远超出单台机器的能力。在 Buildbot 术语中，我们可能需要多个 Worker 在单个构建器配置下并行构建请求。对于一些粗略的估算数字，如果您的构建配置需要 30 分钟，您将需要大约 5-8 个 Worker。如果您的构建配置需要约 2 小时，您将需要大约 20-30 个 Worker。本节的其余部分重点介绍如何缩短周期时间。

限制您构建和测试的内容

认真思考您为什么要设置 Bot，并尽可能限制您的构建配置。基本功能可能已经被其他 Bot 覆盖，您无需重复该测试。您只需要构建和测试配置的独特部分。（例如，对于多阶段 Clang 构建器，您可能不需要启用每个目标或构建所有各种实用程序。）

如果您对同一构建器有多个不同的用途，有时将单个构建器拆分为两个或多个是值得的。例如，如果您既想 a) 确认 LLVM 可以使用您的主机编译器构建，又想 b) 在您的目标上进行多阶段 Clang 构建，那么您最好使用两个单独的 Bot。拆分会增加资源消耗，但使每个 Bot 都能轻松跟上提交流程。此外，拆分 Bot 可以通过将注意力缩小到失败配置的相关部分来协助分类。

一般来说，我们建议启用断言的 Release 构建类型。对于大多数 Buildbot 来说，这通常在构建时间和 Bug 检测之间提供了良好的平衡。可能有一些包含一些调试信息的空间（例如，使用 -gmlt），但总的来说，调试信息质量和构建时间之间的平衡是一个微妙的问题。

使用 Ninja 和 LLD

Ninja 确实有助于缩短构建时间，特别是对于高度并行的构建。LLD 有助于显着减少链接时间和链接期间的内存使用量。对于具有足够并行性的构建机器，链接时间往往主导构建的关键路径，因此值得优化。

使用 CCache 而不是增量构建

使用 ccache 可以显着提高平均构建时间。增量构建可能稍快一些，但会引入由于状态更改等原因导致构建损坏的风险…… 在这一点上，建议不要使用增量构建，而是使用 ccache，因为后者在降低误报风险的情况下捕获了大部分好处。

使用 ccache 的非显而易见的好处之一是，它使构建器对正在监视与构建的项目不太敏感。如果更改触发了构建请求，但没有更改构建输出（例如，文档更改、Python 实用程序更改等），则构建将完全命中缓存，并且构建请求将在测试时间内完成。

对于多个 Worker，很容易尝试配置 Worker 之间共享的缓存。迄今为止的经验表明，这很难做好，并且无论如何，拥有本地的每个 Worker 缓存都可以获得大部分好处。我们目前不建议使用共享缓存。

CCache 确实取决于构建器硬件具有足够的 IO 以合理的访问时间访问缓存 - 即快速磁盘，或足够的内存用于 RAM 缓存等。对于没有这些的构建器，增量可能是您的最佳选择，但可能需要赞助商更高程度的持续参与。

启用批量构建

作为最后的手段，您可以将构建器配置为批量构建请求。这使得构建失败通知的操作性明显降低，并且只有在采取所有其他合理措施后才能这样做。

将其留在暂存 Buildmaster 上

虽然本节的大部分内容都偏向于用于主 Buildmaster 的构建器，但值得强调的是，构建器可以在暂存 Buildmaster 上无限期运行。这样的构建器对于赞助组织仍然可能有用，而无需担心对更广泛的社区产生负面影响。赞助组织只需承担所有二分查找和分类的责任。

从 Web 界面管理 Worker

诸如清除待处理构建请求之类的任务可以使用 Buildbot Web 界面完成。为此，您必须被识别为 Worker 的管理员

  • 将您的公共 GitHub 个人资料电子邮件设置为您在 Worker 上设置的 admin 信息中包含的电子邮件。这是否是您的主要帐户电子邮件或 “已验证的电子邮件” 都没有关系。要确认是否已正确完成此操作，请转到 github.com/<your GitHub username>，您应该在那里看到列出的电子邮件地址。

    如果 Worker 以 First Last <first.last@example.com>, First2 Last2 <first2.last2@example.com> 的形式列出，则 Worker 可以有多个管理员。您只需要在您的个人资料中拥有这些地址之一即可被识别为管理员。

    如果您需要添加电子邮件地址，可以编辑 admin 文件并重启 Worker。您应该在之后不久在 Web 界面中看到新的管理员详细信息。

  • 通过单击页面右上角的 “Anonymous” 按钮，然后单击 “Login with GitHub” 并授权该应用，将 GitHub 连接到 Buildbot。

某些任务不会立即给出反馈，因此如果在短时间内没有任何反应，请在浏览器的 Web 控制台打开的情况下重试。有时您会看到 403 错误和其他消息，这些消息可能表明您没有设置正确的详细信息。