軟體組合

軟體組裝可讓開發人員使用自訂作業系統快速建構產品。具體來說，軟體組裝是一組工具，可從輸入內容 (包括一組 Fuchsia 套件、核心和設定檔) 產生產品組合 (PB)。

產品組合

產品套件是經過妥善指定的構件目錄，可運送至任何環境，並用於刷寫、更新或模擬 Fuchsia 目標。開發人員不應直接檢查 Product Bundle 的內容，而是應使用 Fuchsia 提供的工具。舉例來說，ffx 工具可用於使用產品套件刷新或模擬裝置：

# Flash a hardware target with the product bundle.
$ ffx target flash --product-bundle <PATH/TO/PRODUCT_BUNDLE>

# Start a new emulator instance with the product bundle.
$ ffx emu start <PATH/TO/PRODUCT_BUNDLE>

產品組合可能包含主要和復原產品，兩者是不同的可啟動體驗。main 通常用於實際產品體驗，如果 main 發生故障且無法啟動，則使用 recovery。recovery通常是輕量型體驗，可透過恢復原廠設定或無線 (OTA) 更新，解決 main 插槽中的問題。一般來說，使用者可以在裝置啟動時按住實體按鈕，切換要啟動的產品。

軟體組裝提供建構產品組合的建構工具、定義輸入內容的格式 (平台、產品設定、主機板設定)，以及提供建構這些輸入內容的建構規則。

包含主要產品和復原產品的產品組合

圖 1. 產品組合可能包含主要產品和復原產品。

平台、產品設定和開發板設定

組裝的三項輸入內容 (平台、產品設定、主機板設定) 都是構件目錄。內部格式可能會變更，不應依此格式。開發人員需要使用提供的 Bazel 或 GN 建構規則，建構及使用這些輸入內容。

  • 平台由 Fuchsia 團隊製作，其中包含所有編譯的平台程式碼位元，任何 Fuchsia 產品都可能使用。Fuchsia 團隊會將平台發布至 https://chrome-infra-packages.appspot.com/p/fuchsia/assembly/platform。

  • 產品設定是由開發人員定義使用者體驗所產生。可能包含指出要納入哪些平台功能的旗標。舉例來說，產品設定可以設定 platform.fonts.enabled=true，因此組裝作業會納入平台提供的相關字型支援。如要查看所有可用旗標，請參閱這份參考資料。產品設定檔也可以包含用於建構使用者體驗的自訂程式碼。

  • 主機板設定是由支援特定硬體目標的開發人員產生。其中包含在該硬體上啟動的所有必要驅動程式。 此外，主機板設定可以宣告平台可用的硬體。舉例來說，如果硬體有即時時鐘 (RTC)，主機板設定可以透過設定 provided_features=["fuchsia::real_time_clock"] 標記來指出這點。組件會讀取這個標記，並從平台納入使用這項硬體所需的程式碼。Fuchsia 團隊會維護一小組主機板設定，並發布至 https://chrome-infra-packages.appspot.com/p/fuchsia/assembly/boards。

如何叫用軟體組裝

從核心來看，Fuchsia 的軟體組裝是 Rust 程式庫，多種不同的 CLI 工具都會使用這個程式庫來產生產品組合。下圖說明最常見的組件叫用方式：

  • 建構系統整合 (Bazel 和 GN)：Bazel 和 GN 等建構系統提供簡單的建構目標 (例如 fuchsia_product_bundle，可處理產生正確輸入檔案及為您叫用組裝工具的複雜性。這是最常見且建議使用的軟體組裝方式。

  • ffx product-bundle create：如要快速產生一次性產品套件以供測試，請使用 ffx product-bundle create。使用預先建構的平台、產品和開發板設定時，這個工具特別實用，因為不需要完整整合建構系統，即可快速組裝。

Bazel

# A product bundle can contain both 'main' and 'recovery' products (systems/slots).
fuchsia_product_bundle(
    name = "my_product_bundle",
    main = ":main_product",
    recovery = "...",
)

# A product is a single bootable experience that is built by combining
# a platform, product configuration, and board configuration.
fuchsia_product(
    name = "main_product",
    platform = "//platform:x64",
    product = ":my_product",
    board = "//boards:x64",
)

# A product configuration defines the user experience by enabling
# platform features and including custom product code.
fuchsia_product_configuration(
    name = "my_product",
    product_config_json = {
        platform = {
            fonts = {
                enabled = True,
            },
        },
    },

    # The product code is included as packages.
    base_packages = [ ... ],
)

如需完整範例，請參閱 getting-started 存放區。

指令列介面

ffx product-bundle create --platform 28.20250718.3.1 \
                          --product-config <PATH/TO/MY_PRODUCT_CONFIG> \
                          --board-config cipd://fuchsia/assembly/boards/x64@version:28.20250718.3.1

執行 ffx product-bundle create 指令，即可使用已建構的平台、主機板和產品構件，產生新的產品組合。

靜態分析工具

Software Assembly 提供工具，可驗證產品組合的品質。

大小檢查工具會告知使用者，產品組合是否符合目標硬體的磁碟分割大小限制。您可以使用下列 Bazel 規則產生產品大小報表：

fuchsia_product_size_check(
    name = "main_product_size_report",
    product_image = ":main_product",
)

fuchsia_product(
    name = "main_product",
    ...
)

審查工具可確保產品組合符合一組安全標準。如果開發人員提供必要的審查設定，審查會在建構產品組合時執行。請參閱以下審查設定範例：

fuchsia_product_bundle(
    name = "my_product_bundle",
    main = ":main_product",
    main_scrutiny_config = ":main_scrutiny_config",
)

fuchsia_scrutiny_config(
    name = "main_scrutiny_config",
    base_packages = [ ... ],    # Allowlist of base packages to expect.
    kernel_cmdline = [ ... ],   # Allowlist of kernel arguments to expect.
    pre_signing_policy = "...", # File containing the policies to check before signing.
)

附錄：開發人員覆寫

開發人員有時會想在現有產品上測試某些項目，方法是新增程式碼或切換功能標記。修改產品或主機板設定會汙染 git 樹狀結構 (fuchsia.git)，因此不建議這麼做。組裝作業支援使用開發人員覆寫，在不汙染 git 樹狀結構的情況下，在本機修改現有產品。