如何將您的構建配置添加到 LLVM Buildbot 基礎設施

簡介

本文檔包含有關將構建配置和 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 文件：建立 worker），方法是執行以下指令：

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

    只有在新 worker 穩定且獲得 Galina 的批准（請參閱最後一步）後，才應將其指向主構建主機。

    現在啟動 worker：

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

    這將使您的新 worker 連接到預設為靜默的測試構建主機。

    嘗試連接一次，然後檢查日誌文件 <buildbot-worker 根目錄>/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

    請確保您的構建器名稱及其構建目錄在整個檔案中都是唯一的。

    所有新的構建器預設應使用“‘collapseRequests’: False”設定。這會導致構建器單獨構建每個提交，而不是合併構建請求。為了最大限度地提高對開發人員回饋的品質，我們**強烈建議**將構建器設定為不合併請求。只有在盡一切合理努力縮短構建時間以使構建器能夠跟上提交流程後，才應移除此標記。

    可以允許電子郵件地址在構建失敗時無條件接收通知；為此，您需要將 InformativeMailNotifier 新增至 buildbot/osuosl/master/config/status.py。這對於預設為靜默的測試構建主機特別有用。

  9. 將 buildbot-worker 的存取名稱和存取密碼直接發送給 Galina Kistanova，並等待她通知您您的變更已套用且構建主機已重新設定。

  10. 確保您可以啟動 buildbot-worker 並成功連接到靜默構建主機。然後將您的 buildbot-worker 設定為在開機時自動啟動。如需協助，請參閱 buildbot 文件。您可能需要重新啟動電腦以查看其是否正常運作。

  11. 請檢查您的 buildbot-worker 在 Waterfall 顯示 (預備環境) 的狀態以確保其已連線，並在 Workers 顯示 (預備環境) 中查看管理員聯絡資訊和 worker 資訊是否正確。

  12. 至此，您已擁有一個連接到預備環境 buildmaster 的工作 builder。您現在可以確保它穩定地顯示為綠色，並跟上建置佇列。系統不會發送任何通知，因此您可以無限期地將不穩定的 builder 保持連接到預備環境。

  13. （選用）一旦 builder 在預備環境 buildmaster 上穩定運行數天且歷史記錄為綠色，您可以選擇將其移至正式環境 buildmaster 以啟用開發人員通知。請發送電子郵件至 Galina Kistanova 以供審查和批准。

    要將 worker 移至正式環境（經批准後），請停止您的 worker，編輯 buildbot.tac 檔案以將端口號從 9994 更改為 9990，然後重新啟動它。

配置快速 Builder 的最佳實務

如上所述，我們通常強烈偏好能夠在每次提交時都進行建置的 builder。本節包含最佳實務和一些有關如何實現該目標的建議。

目標

在 2020 年，monorepo 擁有不到 35,000 次提交。這相當於平均每小時 4 次提交。我們已經可以看到，builder 必須在不到 15 分鐘內完成一個週期，才能發揮作用。但是，這些提交並不是均勻分佈的。它們往往集中在美國工作時間。觀察最近（2021 年 11 月）幾個工作日，我們經常看到在高峰時段每小時約有 10 次提交，偶爾會出現每小時高達約 15 次提交的高峰。因此，根據經驗，我們應該規劃我們的 builder 每小時完成約 10-15 個建置。

適當配置資源

以每小時 10-15 個建置的速度，我們需要平均每 4 到 6 分鐘完成一個新的建置。對於除最快硬體/建置配置之外的所有配置，這將遠遠超出單台機器的能力。用 buildbot 的術語來說，我們可能需要多個 worker 在單個 builder 配置下並行建置請求。根據一些粗略的估算，如果您的建置配置需要例如 30 分鐘，您將需要大約 5-8 個 worker。如果您的建置配置需要約 2 小時，您將需要大約 20-30 個 worker。本節的其餘部分將重點介紹如何縮短週期時間。

限制建置和測試的內容

仔細考慮您設置機器人的原因，並盡可能限制您的建置配置。基本功能可能已經被其他機器人覆蓋，您不需要重複該測試。您只需要建置和測試配置的*獨特*部分。（例如，對於多階段 clang builder，您可能不需要啟用每個目標或建置所有不同的工具。）

如果同一個 builder 有多個不同的用途，則有時將其拆分為兩個或多個 builder 是值得的。例如，如果您既想 a) 確認所有 LLVM 都使用您的主機編譯器建置，又想 b) 在您的目標上進行多階段 clang 建置，那麼您最好使用兩個獨立的機器人。拆分會增加資源消耗，但可以讓每個機器人都能輕鬆跟上提交流程。此外，拆分機器人可以透過將注意力集中在失敗配置的相關部分來協助分類。

一般來說，我們建議使用啟用 Assertion 的 Release 組建類型。對於大多數建置機器人來說，這通常能在建置時間和錯誤偵測之間取得良好的平衡。雖然可能還有空間包含一些偵錯資訊（例如使用 -gmlt），但一般來說，偵錯資訊品質和建置時間之間的平衡很微妙。

使用 Ninja 和 LLD

與 Make 相比，Ninja 確實有助於縮短建置時間，特別是對於高度平行化的建置。LLD 有助於顯著減少連結時間和連結期間的記憶體使用量。對於具有足夠平行處理能力的建置機器，連結時間往往會主導建置的關鍵路徑，因此值得最佳化。

使用 CCache 而不是增量建置

使用 ccache 可以顯著改善平均建置時間。增量建置可能會稍微快一些，但會引入由於例如狀態更改等原因導致建置損壞的風險。目前，建議不要使用增量建置，而應使用 ccache，因為後者可以捕捉到大部分的效益，且誤報的風險較低。

使用 ccache 的一個不明顯的好處是，它可以降低建置器對哪些專案正在被監控與建置的敏感度。如果某個變更觸發了建置請求，但沒有改變建置輸出（例如文件變更、Python 工具變更等），則建置將完全命中快取，並且建置請求將在測試時間內完成。

使用多個工作器時，可能會想要嘗試在工作器之間配置共用快取。迄今為止的經驗表明，這很難做好，而且擁有每個工作器的本地快取就能獲得大部分的效益。我們目前不建議使用共用快取。

CCache 的確依賴於建置器硬體具有足夠的 I/O 效能，以便以合理的存取時間存取快取，也就是說需要快速的磁碟或足夠的記憶體來存放 RAM 快取等等。對於沒有這些條件的建置器，增量建置可能是您最好的選擇，但可能需要贊助者持續投入更多心力。

啟用批次建置

作為最後的手段，您可以將建置器配置為批次建置請求。這會使得建置失敗通知的可操作性顯著降低，因此只有在採取所有其他合理措施後才應執行此操作。

將其保留在臨時建置主機上

雖然本節大部分內容都偏向於用於主要建置主機的建置器，但值得強調的是，建置器可以在臨時建置主機上無限期地運行。這樣的建置器可能仍然對贊助機構有用，而不必擔心對更廣泛的社群產生負面影響。贊助機構只需承擔所有歸因和分類的責任。