建構系統政策

本文件將詳細說明設計原則和具體的技術決策 說明 Fuchsia 建構方式的運作方式 舉例來說，這些原則適用於 Fuchsia 版本的所有模式，例如 透過互動式工程工作流程或自動化系統 CI/CQ：

建構的目標和優先順序

如同任何系統，建構作業往往也會存在多項衝突 Google Cloud 就是最佳選擇發生衝突時，我們通常會設法滿足 優先順序排列：

  1. 滿足 Fuchsia 技術主管制定的客戶需求。
  2. 確保內容正確：產生所需的輸出內容。
  3. 提升維護能力：說明文件、健全的工程程序。
  4. 提升效能：以較低的費用執行相同的版本。

想要的建構作業屬性

下列為適合建構的屬性：

  • 遺傳性 - 版本獨立且不會影響外部 或受外部軟體影響 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定
  • 可重複性和可重現性：來自同一來源樹狀結構的兩項建構作業 以確定性的方式產生相同的輸出內容或相同的結果。 可重現性可提升安全性、稽核與簡化 來排解問題
  • 高效率：建構作業只應花時間執行與建構作業相關的工作 ，並將對人力和基礎架構成本的影響降至最低。
  • 可攜性：建構作業應針對所有支援的版本產生一致的結果 代管平台

是理想選擇。 我們致力滿足這些理想，並評估我們在這些措施上的進度。

使用 Python 指令碼做為建構動作

Python 指令碼可用來當做建構動作。

請遵循 Python 適用的 Google 樣式指南。

Fuchsia 目前使用 Python 3.8。所有的 Python 來源都必須從 包括：

#!/usr/bin/env fuchsia-vendored-python

使用殼層指令碼做為建構動作

Shell 指令碼可做為建構動作。

建議使用殼層指令碼來處理工作，只要幾個簡單步驟就能表示 殼層指令如果作業較為複雜，建議使用其他語言。

請按照 Google 殼層指令碼的樣式指南中的指示操作。 請使用 shellcheck 找出並修正常見的殼層程式設計錯誤。

為方便在眾多 代管平台 若您維護現有的 Bash 指令碼，請限制這些功能 版本 3.2，或考慮將指令碼改寫為 POSIX 殼層指令碼。 如要檢查指令碼是否符合 POSIX 規範，可以使用以下方式：

shellcheck --shell=sh

在 POSIX 殼層上執行的指令碼應以下列開頭：

#!/bin/sh

特別需要 Bash 的指令碼開頭應該是：

#!/bin/bash

遷移

建構系統可協助執行以下項目的遷移作業： 包括開發工具、提供新工具，或擴展各種最佳做法。 舊有的不預期行為通常可用依附元件的形式表達 並在套用此行為的 config() 上發布。使用舊版工具 您可以利用 group() 的依附元件擷取要替換的範本 目標。

簽訂方案

改善程式碼健康狀態的方式絕對是接受的，但應該清楚 做好規劃，在開始之前完成後續步驟。透過 與不遷移相比，體驗可能更糟。

建立迴歸停靠站

假設程式碼集每 8 個月會加倍，並盡可能提早運作 來避免出現舊版行為的新例項。變更者： 建立迴歸停靠站的一點就是清理程式碼集 受到加倍率 (意即每倍增率) 也就是被動清理一半的程式碼集

確保許可清單受到 OWNERS 檔案保護，以及網站概念驗證 (POC) 遷移作業會列為擁有者由於擁有者是由檔案定義，因此 最好將許可清單細分為不同的 BUILD.gn 檔案。舉例來說： config() 與 Rust 相關的目標已提取至 //build/config/rust， 更妥善地管理 OWNERS 指派作業。

文件遷移 / 清除步驟

請發布一份清晰的文件，說明遷移的性質、如何 以及如何執行相關維護工作這樣一來 遷移至擴大規模，同時避免員工成為阻礙 持續的遷移工作，例如當他們無法處理支援要求時 或因不方便出席問題

查看 C++ 隱含轉換做為正面範例。

簡化並自動處理許可清單的維護作業

使用 visibility 清單即可輕鬆以 Google GN 指定目標的許可清單形式呈現。開啟 進而實現自動分析，並做出違反許可清單的變更 無法快速執行建構作業

將目標加入許可清單，以便使用即將遷移的舊版行為 後，這些目標的擁有者就可以輕鬆進行簡單的重構，例如 將底層加入許可清單，以便重新命名目錄中個別目標 而非個別目標

記錄重新產生及刪減許可清單的步驟， 由任何人執行。

請參考以下範例：

group("foo_allowlist") {
  #  ________  _________  ________  ________
  # |\   ____\|\___   ___\\   __  \|\   __  \
  # \ \  \___|\|___ \  \_\ \  \|\  \ \  \|\  \
  #  \ \_____  \   \ \  \ \ \  \\\  \ \   ____\
  #   \|____|\  \   \ \  \ \ \  \\\  \ \  \___|
  #     ____\_\  \   \ \__\ \ \_______\ \__\
  #    |\_________\   \|__|  \|_______|\|__|
  #    \|_________|
  # This is an allowlist of targets that use the deprecated "foo" tool.
  # As of April 2021 we no longer use "foo". Users should migrate to the new
  # "bar" tool as described in this guide:
  # https://fuchsia.dev/...
  #
  # To regenerate:
  # fx gn refs $(fx get-build-dir) //path/to:foo_allowlist | sed 's|\(.*\):.*|"\1/*",|' | sort | uniq
  #
  # To trim:
  # scripts/gn/trim_visibility.py --target="//path/to:foo_allowlist"
  visibility = [
    "//src/project1/*",
    "//src/project2/*",
    ...
  ]
}

接著，在許可清單上自動新增依附元件。

# Invoke the legacy foo tool.
# For new usage, please consider using the new bar tool instead!
# See:
# https://fuchsia.dev/...
# ...
template("foo") {
  action(target_name) {
    ...
    deps += [ "//build/foo:foo_allowlist" ]
  }
}

第三方可能不在範圍內

Fuchsia 使用許多第三方程式碼，也就是超出範圍的程式碼 Fuchsia 專案的一環原則上，在毯子內輸入毯子 加入所有第三方程式碼的許可清單，取得明確的變更或政策決策。

group("bar_allowlist") {
  ...
  visibility = [
    "//third_party/*",
    ...
  ]
}

視變更性質和有問題的第三方程式碼而定 上游或許可以變更請謹慎評估。