如何將您的建置配置新增至 LLVM Buildbot 基礎設施

簡介

本文檔包含關於將建置配置和 Buildbot 工作節點新增至 LLVM Buildbot 基礎設施的資訊。

注意

本文檔中使用術語「buildmaster」來指代管理執行哪些建置以及在哪裡執行的伺服器。雖然我們通常不會選擇使用「master」術語，但在本文檔中使用它是因為它是 Buildbot 套件目前使用的術語。

Buildmasters

目前有兩個 buildmaster 正在運行。

  • 主要 buildmaster 位於 https://lab.llvm.org/buildbot。連接到此機器的所有建置器將在每次建置中斷時通知提交作者。

  • 預備 buildmaster 位於 https://lab.llvm.org/staging。連接到此機器的所有建置器在建置中斷時預設為完全靜音。此 buildmaster 每兩小時使用來自 llvm-zorg 儲存庫的任何新提交重新配置。

為了保持與主要 buildmaster 的連線（並因此通知開發人員失敗），builbot 必須

  • 建置受支援的配置。實驗性後端的建置器通常應連接到預備 buildmaster。

  • 能夠跟上主分支的新提交，或至少在落後後幾天內恢復到樹狀結構的頂端。

此外，我們鼓勵所有機器人所有者在維護期間、不穩定性故障排除等情況下將其機器人指向預備主控台。

角色與期望

每個 buildbot 都有一個所有者，該所有者是對所述 buildbot 出現的問題負責的一方。我們通常希望機器人所有者能夠合理地做出回應。

對於某些機器人，所有權責任在提供底層機器資源的「資源所有者」和維護建置配置的「配置所有者」之間分配。通常，營運責任在於「配置所有者」。我們確實希望「資源所有者」（通常是工作節點屬性中列出的聯絡人）及時將請求轉發給相關的「配置所有者」。

大多數與 buildbot 相關的問題應直接透過電子郵件與機器人所有者聯繫。請副本抄送 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 存取名稱和密碼，build master 將使用它們來驗證您的 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 的批准後（請參閱最後一步），才應將其指向主要 buildmaster。

    現在啟動工作節點

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

    這將使您的新工作節點連線到預設為靜音的預備 buildmaster。

    嘗試執行一次，然後檢查日誌檔 <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

    請確保您的建置器名稱及其 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 在 瀑布顯示 (預備) 上的狀態，以確保它已連線，並檢查 工作節點顯示 (預備) 以查看管理員聯絡資訊和工作節點資訊是否正確。

  12. 此時，您已擁有一個可運作的建置器，該建置器已連線到預備 buildmaster。您現在可以確保它可靠地保持綠色，並跟上建置佇列。不會發送通知，因此您可以將不穩定的建置器無限期地連線到預備環境。

  13. （可選）一旦建置器在預備 buildmaster 上穩定運行並具有數天的綠色歷史記錄，您可以選擇將其移動到生產 buildmaster 以啟用開發人員通知。請發送電子郵件給 Galina Kistanova 以進行審查和批准。

    若要將工作節點移動到生產環境（獲得批准後），請停止您的工作節點，編輯 buildbot.tac 檔案以將端口號碼從 9994 變更為 9990，然後再次啟動它。

在本機測試建置器配置

可以針對 LLVM buildmaster 設定的本機版本測試正在運行的建置器。這允許您測試對建置器、工作節點和 buildmaster 配置的變更。在此「本機測試」模式下啟動的 buildmaster 將

  • 僅綁定到本機介面。

  • 使用 SQLite 作為資料庫。

  • 對工作節點使用單個固定密碼。

  • 停用 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 工作節點。確保您為與您想要在 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 中查看建置的進度和結果。

出於安全考量，此本機測試配置預設僅綁定到迴路介面。

如果您想要在不同的機器上運行測試工作節點，或者在遠端伺服器上運行 buildmaster，則可以使用 ssh 端口轉發來建立連線。例如，如果在遠端伺服器上運行 buildmaster，以下命令足以使 Web UI 可透過 https://127.0.0.1:8011 存取，並使本機工作節點可以透過連線到 localhost:9900 連線到遠端 buildmaster

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

請注意，某些建置配置可能會檢查目前的上游 llvm-zorg 儲存庫，以便檢索建置過程中使用的其他腳本，這表示任何本機變更都不會反映在建置的這部分中。如果您希望在不將變更提交到上游的情況下測試對這些腳本的變更，您需要暫時修補建置器邏輯，以便改為檢查您自己的分支。通常，zorg/buildbot/process/factory.py 中的 addGetSourcecodeForProject 用於此目的，您可以編輯呼叫者以指定您自己的 repourl 和/或 branch 關鍵字引數。

配置快速建置器的最佳實務

如上所述，我們通常強烈偏好可以建置每個傳入提交的建置器。本節包含最佳實務以及關於如何實現此目標的一些建議。

目標

在 2020 年，monorepo 剛好有不到 35,000 次提交。這相當於平均每小時 4 次提交。我們已經可以看到，建置器必須在不到 15 分鐘內循環一次，才有希望發揮作用。但是，這些提交並非均勻分佈。它們往往在美國工作時間內強烈聚集。查看最近幾天（2021 年 11 月）的工作日，我們經常看到在尖峰時段每小時約有 10 次提交，偶爾高峰高達每小時約 15 次提交。因此，作為經驗法則，我們應該計劃讓我們的建置器每小時完成約 10-15 次建置。

適當配置資源

在每小時 10-15 次建置的情況下，我們平均需要每 4 到 6 分鐘完成一次新的建置。對於除最快的硬體/建置配置之外的任何配置，這將遠遠超出單一機器的能力。在 buildbot 術語中，我們可能需要多個工作節點來在單個建置器配置下並行建置請求。對於一些粗略的概略數字，如果您的建置配置需要例如 30 分鐘，您將需要大約 5-8 個工作節點。如果您的建置配置需要約 2 小時，您將需要大約 20-30 個工作節點。本節的其餘部分重點介紹如何縮短循環時間。

限制您建置和測試的內容

仔細思考您為什麼要設定機器人，並盡可能限制您的建置配置。基本功能可能已經被其他機器人涵蓋，您不需要重複該測試。您只需要建置和測試配置的獨特部分。（例如，對於多階段 clang 建置器，您可能不需要啟用每個目標或建置所有各種實用程式。）

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

一般來說，我們建議啟用斷言的發行版本建置類型。這通常在大多數 buildbot 的建置時間和錯誤檢測之間提供了良好的平衡。可能有空間包含一些偵錯資訊（例如使用 -gmlt），但總體而言，偵錯資訊品質和建置時間之間的平衡是一個微妙的問題。

使用 Ninja 和 LLD

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

使用 CCache 而非增量建置

使用 ccache 可以顯著縮短平均建置時間。增量建置可能會稍快一些，但會因狀態變更等原因而引入建置損壞的風險... 此時，建議不要使用增量建置，而是使用 ccache，因為後者在降低誤報風險的同時，也捕捉到了大部分好處。

使用 ccache 的非顯而易見的好處之一是，它使建置器對正在監視與建置的專案不太敏感。如果變更觸發了建置請求，但沒有變更建置輸出（例如文件變更、python 實用程式變更等），則建置將完全命中快取，並且建置請求將在測試時間內完成。

對於多個工作節點，很容易嘗試在工作節點之間配置共享快取。迄今為止的經驗表明，這很難做好，並且無論如何，擁有本機每工作節點快取也能獲得大部分好處。我們目前不建議使用共享快取。

CCache 確實取決於建置器硬體具有足夠的 IO 來以合理的存取時間存取快取 - 即快速磁碟，或足夠的記憶體用於 RAM 快取等。對於沒有這些的建置器，增量可能是您的最佳選擇，但可能需要贊助商更高的持續參與度。

啟用批次建置

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

將其留在預備 buildmaster 上

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

從 Web 介面管理工作節點

可以使用 Buildbot Web 介面完成諸如清除待處理建置請求之類的任務。為此，您必須被識別為工作節點的管理員

  • 將您的公開 GitHub 個人資料電子郵件設定為您在工作節點上設定的 admin 資訊中包含的電子郵件之一。這是否是您的主要帳戶電子郵件或「已驗證的電子郵件」都沒關係。要確認是否已正確完成此操作，請前往 github.com/<your GitHub username>，您應該在那裡看到列出的電子郵件地址。

    如果工作節點以 First Last <first.last@example.com>, First2 Last2 <first2.last2@example.com> 的形式列出，則工作節點可以有多個管理員。您只需要在您的個人資料中擁有這些地址之一即可被識別為管理員。

    如果您需要新增電子郵件地址，您可以編輯 admin 檔案並重新啟動工作節點。您應該在稍後在 Web 介面中看到新的管理員詳細資訊。

  • 透過點擊頁面右上角的「Anonymous」按鈕，然後點擊「Login with GitHub」並授權應用程式，將 GitHub 連線到 Buildbot。

某些任務不會立即提供回饋，因此如果在短時間內沒有任何反應，請在瀏覽器的 Web 控制台中重新嘗試。有時您會看到 403 錯誤和其他訊息，這些訊息可能表明您沒有設定正確的詳細資訊。