使用開發人員覆寫值組合 Fuchsia 產品

Fuchsia 建構系統會結合平台、產品和主機板設定，建立最終的產品套件。雖然這些設定定義了產品的標準版本，但您可能需要進行暫時性修改，以利測試或偵錯。如要進一步瞭解軟體組裝的概念資訊，請參閱「軟體組裝」。

開發人員覆寫機制可讓您對產品設定進行僅限本機的修改，不必變更 Fuchsia 樹狀結構中的來源檔案。

本文說明如何使用開發人員覆寫功能修改產品的設定。

使用組件覆寫

如要使用組裝的開發人員覆寫功能，請按照下列步驟操作：

  1. 在 GN 目標中定義覆寫，通常是在 //local/BUILD.gn 中。
  2. 將覆寫內容套用至建構設定。

舉例來說，如要啟用核心引數，請先在 //local/BUILD.gn 中定義覆寫：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("enable_kernel_debug") {
  kernel = {
    command_line_args = [ "foo" ]
  }
}

然後，使用下列其中一種方法，將這項覆寫套用至建構設定：

使用fx set

fx set 指令包含 --assembly-override 選項，可指定主要產品組件的覆寫 (而非測試組件、復原等)。例如：

fx set core.x64 --assembly-override //local:enable_kernel_debug

--assembly-override 選項支援兩種格式：

  • --assembly-override <overrides_target>：將覆寫內容套用至主要產品組件。

    舉例來說，下列指令會將 //local:enable_kernel_debug 覆寫套用至 core.x64 產品：

    fx set core.x64 --assembly-override //local:enable_kernel_debug

  • --assembly-override <assembly_target_pattern>=<overrides_target>：將覆寫項目套用至特定組件目標模式。

    舉例來說，如要只將 //local:zedboot_overrides 中定義的覆寫套用至 zedboot 組件，請執行下列指令：

    fx set core.x64 --assembly-override '//build/images/zedboot/*=//local:zedboot_overrides'

詳情請參閱下列章節：

使用 fx args 或 args.gn

您可以編輯 args.gn 檔案或使用 fx args 來套用覆寫。可用的 GN 引數如下：

product_assembly_overrides_label

product_assembly_overrides_label 引數會將指定的覆寫項目套用至所選產品的主要組件。這不會影響其他產品組合，例如復原、zedboot 或測試。

args.gn 範例：

import("//products/...")
import("//boards/...")

product_assembly_overrides_label = "//local:my_overrides"

product_assembly_overrides_contents

您可以使用 product_assembly_overrides_contents 引數，直接在 args.gn 中定義覆寫。這些覆寫設定只會套用至主要產品組裝。

args.gn 範例：

import("//products/...")
import("//boards/...")

product_assembly_overrides_contents = {
  kernel = {
    command_line_args = [ "kernel.enable-debugging-syscalls=true" ]
  }
}

這個值使用的語法與 assembly_developer_overrides() GN 範本相同，請參閱「定義 assembly_developer_overrides 目標」。

product_assembly_overrides

product_assembly_overrides 引數可用於指定多個或非主要組件的覆寫項目。這項功能會使用 GN 標籤模式，將覆寫目標與對應的組件目標配對。

args.gn 範例：

import("//products/....")
import("//boards/....")

product_assembly_overrides = [
  {
    # zedboot
    assembly = "//build/images/zedboot/*"
    overrides = "//local:zedboot_overrides"
  },
  {
    # For assemblies in Bazel, use their product label
    assembly = "//products/minimal/*"
    overrides = "//local:minimal_overrides"
  },
  {
    # core or terminal products:
    assembly = "//build/images/fuchsia/*"
    overrides = "//local:enable_kernel_debug"
  },
]

定義 assembly_developer_overrides 目標

如要定義一組開發人員覆寫項目，請在 BUILD.gn 檔案中使用 assembly_developer_overrides() 範本。建議您將這些定義放在 Fuchsia 結帳的 //local 目錄中，因為這個目錄會遭到 Git 忽略。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("enable_kernel_debug") {
  kernel = {
    command_line_args = [
      "foo",
    ]
  }
}

# Multiple override sets can be defined in the same file.
assembly_developer_overrides("bar_debug") {
  kernel = {
    command_line_args = [ "bar" ]
  }
}

可用的覆寫選項

以下各節說明可在 assembly_developer_overrides 目標中設定的可用選項：

僅限開發人員使用的組裝選項

這些組裝選項只能透過開發人員覆寫啟用，且通常不允許用於產品或主機板設定。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("netboot_with_all_packages") {
  developer_only_options = {
    all_packages_in_base = true
    netboot_mode = true
  }
}
  • all_packages_in_base：將所有 cache 和 on_demand 套件重新導向至 base 套件組合。如果網路無法運作，這項功能有助於在裝置上使用偵錯工具。
  • netboot_mode：建立 Zircon 開機映像檔 (ZBI)，其中包含 ramdisk 內的 FVM/Fxfs 映像檔，讓產品能夠透過網路開機。

平台設定

您可以覆寫產品組裝件設定的 platform 設定。詳情請參閱 PlatformSettings 參考資料。

系統會根據欄位，將您指定的值與產品的平台設定合併。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("enable_sl4f") {
  platform = {
    development_support = {
      include_sl4f = true
      include_netsvc = true
    }
  }
}

如要將項目附加至清單，而非取代清單，請參閱「使用 __append_to_<key> 將項目附加至清單」。

核心指令列引數

您可以新增核心指令列引數。系統不會保留核心指令列引數的順序。如需可用選項的清單，請參閱 Zircon 核心指令列選項說明文件。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("bar_debug") {
  kernel = {
    command_line_args = [ "bar" ]
  }
}

其他套件

您可以將開發人員指定的套件新增至 base、cache、bootfs 和 flexible 套件組合。flexible 套件組合會放在 cache 中，適用於 eng 建構類型，並放在 base 中，適用於 user 和 userdebug 建構類型。

範本需要套件的特定 GN 標籤，且不會使用 GN 中繼資料來遍歷套件群組。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("my_custom_base_packages") {
  base_packages = [
    "//some/gn/target/for/a:package",
    "//some/other/target/for/a:package",
    "//third_party/sbase",
  ]
}

殼層指令

如要將指令列工具新增至 Fuchsia Shell，您必須新增包含該工具的套件，並指示組件建立元件的啟動器存根。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("my_custom_shell_commands") {
  shell_commands = [
    {
      package = "cp"
      components = [ "cp" ]
    }
  ]
}

如果透過套件探索功能提供套件仍不夠，您也可以將套件新增至套件集。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("my_custom_shell_commands") {
  shell_commands = [
    {
      package = "cp"
      components = [ "cp" ]
    }
  ]

  # This GN target should define a package named "cp".
  base_packages = [
    "//some/gn/target/for/my/package:cp"
  ]
}

開發板設定

您可以覆寫特定開發板的設定，測試變更或新功能。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("add_new_feature") {
  board = {
    provided_features = [ "fuchsia::new_feature" ]
    filesystems = {
      gpt_all = true
    }
  }
}

如要將項目附加至清單，而非取代清單，請參閱「使用 __append_to_<key> 將項目附加至清單」。

已編譯的套件和元件

您可以將開發人員指定的內容和 CML 分片新增至由組件編譯的套件和元件。

//local/BUILD.gn 範例：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("add_core_shard") {
  core_shards = [ "//local/testing.core_shard.cml" ]
}

使用 __append_to_<key> 將項目附加至清單

根據預設，開發人員覆寫會以您指定的新內容取代清單。如要改為附加至清單，請使用 __append_to_<key> 語法，其中 <key> 是清單名稱。

舉例來說，假設有下列開發板設定：

board_configuration("bar") {
  provided_features = [ "fuchsia::feature1", "fuchsia::feature2"]
}

您可以使用這項覆寫項目附加新功能：

import("//build/assembly/developer_overrides.gni")

assembly_developer_overrides("foo") {
  board = {
    __append_to_provided_features = [ "fuchsia::new_feature" ]
  }
}

產生的設定如下所示：

board: {
  provided_features: [
    "fuchsia::feature1",
    "fuchsia::feature2",
    "fuchsia::new_feature",
  ]
}

重要詳細資訊

組裝警告文字

使用覆寫的組裝作業一律會產生警告，詳細說明套用的覆寫。例如：

WARNING!:  Adding the following via developer overrides from: //local:enable_kernel_debug

  Additional kernel command line arguments:
    foo

產品標籤模式

系統會透過標籤模式比對，建立覆寫目標與產品組合之間的對應關係。

  • //some/label/with/wildcard/*：比對該路徑和路徑下的所有組件。
  • //some/label/with/wildcard:*：只比對該資料夾中的所有組件。

建構圖中的不同路徑會找到不同的組件。常見位置包括：

  • GN 組裝產品：
    • bringup 個產品：//build/images/bringup/*
    • core 個產品：//build/images/fuchsia/*
    • zedboot：//build/images/zedboot/*
    • guest：//build/images/guest/*
  • Bazel 組裝產品 (minimal、terminal、workbench 等)：
    • 登機時間：fuchsia.git //products/<name>/*