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

简介

本文档包含有关将构建配置和构建机器人工作器添加到 LLVM Buildbot 基础设施的私有工作器构建器中的信息。

构建主机

有两个构建主机正在运行。

  • 主构建主机位于 https://lab.llvm.org/buildbot。附加到此机器的所有构建器都会在每次破坏构建时通知提交作者。

  • 暂存构建主机位于 https://lab.llvm.org/staging。默认情况下，附加到此机器的所有构建器在构建中断时将完全静默。此构建主机每两小时重新配置一次，并使用 llvm-zorg 代码库中的任何新提交。

为了保持与主构建主机的连接（从而通知开发人员故障），构建机器人必须

  • 正在构建受支持的配置。实验性后端的构建器通常应附加到暂存构建主机。

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

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

角色和期望

每个构建机器人都有一个所有者，该所有者负责解决与该构建机器人相关的任何问题。我们通常期望机器人所有者能够做出合理的响应。

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

大多数构建机器人的问题应直接通过电子邮件与机器人所有者联系。请抄送 Galina Kistanova。

将构建器添加到 LLVM Buildbot 的步骤

志愿者可以提供其构建机器作为构建工作器来工作到公共 LLVM Buildbot。

以下是可以遵循的步骤

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

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

  3. 安装 buildbot-worker（目前我们使用的是 buildbot 版本 2.8.4）。可以使用 pip 安装此特定版本，使用以下命令：pip3 install buildbot-worker==2.8.4。

  4. 创建一个指定的用户信息，您的 buildbot-worker 将在其下运行，并设置相应的权限。

  5. 选择 buildbot-worker 根目录（所有构建都将放在其下）、buildbot-worker 访问名称和构建主机将用于对您的 buildbot-worker 进行身份验证的密码。

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

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

    仅当新工作器稳定且收到 Galina 的批准（请参阅最后一步）后，才应将其指向主构建主机。

    现在启动工作器

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

    这将导致您的新工作器连接到默认情况下静默的暂存构建主机。

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

  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. 发送一个补丁，将您的构建工作器和构建器添加到 zorg。使用典型的 LLVM 工作流程。

    • 工作器添加到 buildbot/osuosl/master/config/workers.py

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

    请确保您的构建器名称及其构建目录在整个文件中都是唯一的。

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

    可以允许电子邮件地址在构建失败时无条件接收通知；为此，您需要将 InformativeMailNotifier 添加到 buildbot/osuosl/master/config/status.py。这对于否则静默的暂存构建主机特别有用。

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

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

  11. 在 瀑布显示（暂存） 上检查您的 buildbot-worker 的状态，以确保它已连接，并在 工作器显示（暂存） 上查看管理员联系人，以及工作器信息是否正确。

  12. 此时，您有一个连接到暂存构建主机的正常工作的构建器。您现在可以确保它可靠地变为绿色并跟上构建队列。不会发送任何通知，因此您可以无限期地将不稳定的构建器连接到暂存。

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

    要将工作器移动到生产环境（经批准后），请停止您的工作器，编辑 buildbot.tac 文件以将端口号从 9994 更改为 9990，然后重新启动它。

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

如上所述，我们通常非常偏爱能够构建每个提交的构建器。本节包含最佳实践以及一些关于如何实现此目标的建议。

目标

2020 年，单一代码库刚刚低于 35000 次提交。这相当于每小时平均 4 次提交。我们已经可以看到，构建器必须在不到 15 分钟内完成循环才能有希望发挥作用。但是，这些提交并非均匀分布。它们往往在美东工作时间内高度集中。查看最近几天（2021 年 11 月）的工作日，我们经常在高峰时段看到每小时约 10 次提交，偶尔会出现高达每小时约 15 次提交的峰值。因此，根据经验法则，我们应该计划我们的构建器每小时完成约 10-15 次构建。

合理利用资源

每小时 10-15 次构建，我们需要平均每 4 到 6 分钟完成一次新构建。对于除最快硬件/构建配置之外的任何内容，这都将远远超出单台机器的能力。用构建机器人的术语来说，我们可能需要多个工作器在单个构建器配置下并行构建请求。对于一些粗略的估算，如果您的构建配置需要例如 30 分钟，您将需要大约 5-8 个工作器。如果您的构建配置需要约 2 小时，您将需要大约 20-30 个工作器。本节的其余部分重点介绍如何减少循环时间。

限制您构建和测试的内容

认真思考您设置机器人的原因，并尽可能限制您的构建配置。其他机器人可能已经涵盖了基本功能，您不需要重复这些测试。您只需要构建和测试配置的 *唯一* 部分。（例如，对于多阶段 clang 构建器，您可能不需要启用每个目标或构建所有各种实用程序。）

如果对同一构建器有几个不同的用途，有时将一个构建器拆分为两个或更多构建器是值得的。例如，如果您希望 a) 确认所有 LLVM 都可以使用您的主机编译器构建，以及 b) 想要在您的目标上进行多阶段 clang 构建，那么使用两个单独的机器人可能更好。拆分会增加资源消耗，但使每个机器人都能轻松跟上提交流程。此外，拆分机器人可以通过将注意力缩小到故障配置的相关部分来帮助进行故障排除。

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

使用 Ninja 和 LLD

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

使用 CCache 而不是增量构建

使用 ccache 从根本上提高了平均构建时间。增量构建可能稍微快一些，但会引入由于例如状态更改等导致的构建损坏的风险……此时，建议不要使用增量构建，而是使用 ccache，因为后者以较低的误报风险捕获了大部分好处。

使用ccache一个不太明显的优势在于，它使得构建器对哪些项目正在被监控与构建不太敏感。如果一个更改触发了构建请求，但没有改变构建输出（例如文档更改、Python工具更改等），则构建将完全命中缓存，构建请求将在测试时间内完成。

使用多个工作器时，可能会想尝试在工作器之间配置共享缓存。迄今为止的经验表明，这很难做好，并且每个工作器拥有本地缓存就能获得大部分收益。我们目前不推荐使用共享缓存。

CCache确实依赖于构建器硬件具有足够的IO来以合理的访问时间访问缓存——即快速磁盘，或足够的内存用于RAM缓存等。对于没有这些的构建器，增量构建可能是您的最佳选择，但可能需要赞助者持续投入更多精力。

启用批处理构建

作为最后的手段，您可以配置构建器来批量构建请求。这使得构建失败通知明显不那么实用，并且只应在采取了所有其他合理措施后才进行。

保留在暂存构建主机上

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