原始碼版面配置

正在搜尋原始碼

如要查看及搜尋 Fuchsia 原始碼，以下選項可供您使用：

總覽

大部分的第一方開放原始碼位於 "fuchsia.git" 存放區。這個存放區中的大部分程式碼都會整理為區域的遞迴樹狀結構。

區域具有一般的內部和依附元件結構。fuchsia.git 存放區本身遵循區域結構，但也有頂層特有的額外結構。

具體來說，fuchsia.git 的 src 頂層目錄可視為根區域。其是遵循區域所需的結構，同時也是子區域所在的位置。不過，部分需要區域的目錄也出現在 src 旁邊，而不是 ，例如 third_party。可想成全球要仰賴的全域範圍。src 以外的其他地方也會保留更多頂層區域，例如 vendor/* 中。開放原始碼 third_party 適用於所有地區。

來源存放區 (包括開放原始碼或封閉原始碼) 也會遵循區域的慣例，並會對應至 fuchsia.git 中的 src 子目錄。目前我們只有少數這類「花瓣」存放區，但隨著系統穩定，我們會將目前在 fuchsia.git 存放區中的區域「升級」至獨立的存放區。

vendor/* 目錄包含封閉原始碼，由該程式碼的供應商整理。//vendor 以外的任何元件皆無法依附於 //vendor。支援不同供應商之間的依附元件，vendor/A 可在 vendor/B 中擁有依附元件。

products 目錄包含您可建構的產品清單。有些產品相當小且快速建構 (例如「核心」產品)，其他產品則較為精緻 (例如 workbench_eng 產品)。

sdk 目錄包含構成 Fuchsia API Surface 的程式庫。其中有些程式庫是用戶端程式庫，其他程式庫則是 FIDL 程式庫。這些程式庫並未全都在 Fuchsia SDK 中發布。所有非測試 FIDL 程式庫都應放在 //sdk/fidl 目錄中，並以 FIDL 程式庫名稱整理，包括僅供在 Fuchsia 平台來源樹狀結構中使用的程式庫。這些程式庫可以使用預設的 internal sdk_category，這會阻止發行給合作夥伴，或者也可以明確標示 internal，透過註解通知使用者預期用途。

大多數的第三方依附元件會儲存在不同的存放區中。只有在需要支援以下任一原始碼樹狀結構設定時，本機結帳功能才會納入這些存放區：

  • Bringup：此來源樹狀結構設定包含足夠的程式碼，可建構橋接產品。
  • 開放原始碼。這個來源樹狀結構設定包含 Fuchsia 來源樹狀結構中的所有開放原始碼。
  • 所有來源。這個來源樹狀結構設定包含 Fuchsia 來源樹狀結構中的所有開放和封閉原始碼。

請參閱指南，瞭解如何在 README.fuchsia 檔案中寫入第三方程式碼的中繼資料。

區域

大部分程式碼都會整理成以遞迴方式排列的區域。每個區域都有一般的內部和依附元件結構，可協助使用者瞭解整個專案的程式碼結構。

目錄結構

每個區域都需要擁有 OWNERS 檔案、說明文件和測試。區域也可以包含二進位檔、程式庫、驅動程式和其他原始碼。此外，區域也可能有子區域，重複這種模式：

  • OWNERS
  • BUILD.gn
    • 定義區域標準目標的建構檔案。除了標準目標之外，區域擁有者還可以加入其他目標。
  • docs/
    • 這個目錄應包含適合這個區域員工的文件
    • 適用於開發人員 (或 Fuchsia 其他區域作業人員) 的文件應位於頂層文件或 SDK 存放區中
  • bundles/
    • 這個目錄包含這個區域的套件目標套裝組合。每個區域至少應包含一個含有該區域單元測試的 tests 組合，但可以包含其他套裝組合。
  • bin/ (非必要)
  • lib/ (非必要)
  • drivers/ (非必要)
  • examples/ (非必要)
  • tests/ (選用)
    • 這個目錄包含整合測試，測試範圍涵蓋同一領域的多個原始碼目錄
    • 如果不同的區域可在子目錄中進行測試，建議您為不同測試目錄新增 OWNERS 檔案，以釐清擁有權。
    • 針對單一二進位檔或程式庫的單元測試，最好與測試的程式碼一起放置
  • testing/ (選用)
    • 這個目錄包含公用程式和程式庫，適合用來在這個區域和子區域編寫測試。
    • 這個目錄中的目標只能依附於測試專用的目標。
  • third_party/ (選用)
    • 大多數的 third_party 依附元件應位於不同的存放區
    • 只有在符合下列所有條件時，才能在區域中加入 third_party 依附元件：
      • 依據政策規定，程式碼必須存放在 third_party 目錄中
      • 您打算針對上游建立分支 (即進行重大變更，且不打算整合上游未來的變更)
      • 為程式碼建立新名稱，且 (a) 與上游不符，且 (b) 也並未出現在 Fuchsia 來源樹狀結構中的任何第三方目錄內
      • 程式碼為開放原始碼
    • 如要進一步瞭解 third_party 來源版面配置，請參閱第三方原始碼管理。
  • tools/ (選用)
    • 這個目錄包含區域提供的指令列工具。這些元件通常可以 (或必須) 為開發主機 (而非 Fuchsia) 建構。不一定可直接在區域本身的建構作業中使用，但開發人員也可使用。不一定能在 SDK 中發布。這個版本中使用的特殊用途工具不適合開發人員直接使用，應存放在其用途附近，而非此處。
    • 這應包含為每個工具 (或具有自然集合名稱的相關工具集合) 命名的子目錄，而不是將區域的所有工具都放在頂端的 tools/BUILD.gn 檔案中。
  • [subareas] (選用)
    • 子區域應採用一般區域範本
    • 請勿建立深層巢狀的區域結構，例如三個應足夠。

除了列舉目錄外，區域可能也會為內部機構使用其他目錄。

擁有者

每個區域和子區域都必須包含一個 OWNERS 檔案。目錄可包含 OWNERS，但不視為區域，例如頂層 products 目錄或 /src/lib 目錄的子目錄。缺少 OWNERS 檔案的目錄會與相同區域的父項目錄具有相同的擁有者。

有一個例外是 //src/tests 目錄，其中涵蓋系統的多個層面 (而不只是特定區域) 的測試預計會上線。因此，每個區域都應該針對此目錄中的任何測試新增 OWNERS 檔案。

依附元件結構

除了取決於本身，區域只能依附頂層 build、sdk 和 third_party 目錄，以及樹狀結構中任何位置的 lib 目錄：

  • //build
  • //sdk
  • //third_party
  • //src/**/lib/

在建構系統中標示為僅受測試的區域，目標可能也會進一步依附於該區域和祖系的 testing 目錄：

  • (../)+testing/ (僅限 testonly=true 個目標)

標準目標

每個區域和子區域都必須在其頂層 BUILD.gn 檔案中定義下列標準目標：

  • <dir-name>

    • 所有目錄的目標名稱都應與目錄相同。目錄目標基本上是「all」目標，旨在產生「打造一切」版本。
    • 目錄和子目錄中定義的所有可建構構件。
    • 目前目錄和子目錄中的所有測試。
    • 目錄目標只能產生最高的版本，不應包含會修改特定產品「產品行為」的設定目標或變更。舉例來說，加入目錄目標不應導致系統在啟動時自動啟動新軟體，也不會覆寫預設服務拓撲或服務對應。
    • 將新的子目錄新增至區域時，其應定義這個目錄名稱目標，以及在父項目錄目標中包含目錄名稱目標。

  • tests

    • 這個領域中的所有測試
    • 為新的測試目標加入新的子目錄時，測試目標應新增至父項目錄測試目標。

命名慣例

命名檔案和目錄時，最佳做法是使用簡短清晰的名稱。如果名稱由多個字詞組成，這些字詞必須以底線分隔，例如 long_file_name。

範例

以下是名為 fortune 目錄的範例。

import("//build/drivers.gni")
import("//build/components.gni")

group("fortune") {
  testonly = true
  deps = [
    ":pkg",
    ":tests",
  ]
}

group("tests") {
  testonly = true
  deps = [
    ":fortune_tests"
  ]
}

executable("bin") {
  output_name = "fortune"

  sources = [
    "fortune.cc"
  ]
}

executable("test") {
  testonly = true
  output_name = "fortune-test"

  sources = [
    "test.cc"
  ]
}

fuchsia_component("component") {
  manifest = "meta/fortune.cml"
  deps = [ ":bin" ]
}

fuchsia_package("pkg") {
  package_name = "fortune"
  deps = [ ":component" ]
}

fuchsia_unittest_package("fortune_tests") {
  deps = [ ":test" ]
}

存放區版面配置

本節說明 Fuchsia 來源樹狀結構的目錄版面配置。無星號的項目是指 fuchsia.git 存放區中的目錄或檔案。已加星號 (*) 項目是獨立的存放區，這些存放區使用 jiri 對應至目錄結構 (預先建構的目錄是由 CIPD 填入的目錄除外)。

  • .clang-format
  • .dir-locals.el
  • .gitattributes
  • .gitignore
  • AUTHORS
  • CODE_OF_CONDUCT.md
  • CONTRIBUTING.md
  • LICENSE
  • OWNERS
  • PATENTS
  • README.md
  • rustfmt.toml
  • sdk/banjo/fuchsia.hardware.gpio/
  • sdk/banjo/...
  • sdk/fidl/fuchsia.media/
  • sdk/fidl/fuchsia.mediacodec/
  • sdk/fidl/...
  • sdk/lib/ddk/
  • sdk/lib/fit/
  • sdk/lib/fidl/
  • sdk/lib/zircon/
  • sdk/lib/...
  • .gn
  • BUILD.gn
  • build/
  • bundles/
  • configs/
  • infra/
    • configs/
      • generated/
  • integration/
  • products/
  • scripts/
  • docs/
  • examples/
  • third_party/
    • boringssl/ *
    • icu/ *
    • rust_crates/ *
    • ... *
  • prebuilt/
    • chromium/ *
    • llvm/ *
  • tools/
    • banjo/
    • fidl/bin/backend/{c,cpp,dart,go,llcpp,rust}
    • fidl/bin/frontend/
    • fidl/docs/
    • fidl/examples/
    • fidl/tests/
  • src/
    • lib/
    • cobalt/
    • component/
    • connectivity/
    • developer/
    • experiences/ *
    • graphics/
    • identity/
    • media/
    • storage/
    • testing/
    • ui/
      • scenic/
    • updater/
    • virtualization/
    • zircon/kernel/
    • zircon/drivers/
    • zircon/userspace/
  • vendor/
    • [closed-source code from various vendors] *

演進

當系統穩定時，可以將 fuchsia.git 以外的區域推送至不同的存放區。一般來說，當系統區域與其餘部分之間的介面足夠穩定 (必須獲得頂層 OWNERS 核准) 時，我們應將區域推送至獨立存放區。

新的程式碼可以是：

  • 已新增至 fuchsia.git 中的現有目錄
  • 已新增至現有區域的新頂層區域或子區域
  • 已新增至現有存放區
  • 已新增至新的存放區 (必須獲得頂層 OWNERS 的核准)