原始碼版面配置

搜尋原始碼

如要查看及搜尋 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 目錄包含您可以建構的產品清單。有些產品相當小，且建構速度快 (例如 core 產品)，其他產品則較為複雜 (例如 workbench_eng 產品)。

sdk 目錄包含組成 Fuchsia API 途徑的程式庫。其中有些程式庫是用戶端程式庫，其他則是 FIDL 程式庫。但並非所有這些程式庫都會在 Fuchsia SDK 中發行。所有非測試 Fidl 程式庫都應放置在 //sdk/fidl 目錄中，並依 Fidl 程式庫名稱進行排序，包括僅供 Fuchsia 平台來源樹系內使用的程式庫。這些程式庫可以使用 internal 的預設 sdk_category，這樣就不會分發給合作夥伴；或者，您也可以明確標示 internal，並附上註解提醒使用者其預期用途。

大部分的第三方依附元件都儲存在個別的存放區中。只有在需要支援下列其中一種來源樹狀結構設定時，這些存放區才會納入本機檢出的項目：

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

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

區域

大部分的程式碼會整理成區域的遞迴樹狀結構。每個區域都有常規的內部和依附元件結構，可協助使用者瞭解整個專案的程式碼結構。

目錄結構

每個區域都必須有 OWNERS 檔案，以及相關文件和測試。區域也可以包含二進位檔、程式庫、驅動程式和其他原始碼。此外，區域可以有子區域，而子區域會重複這個模式：

  • OWNERS
  • BUILD.gn
    • 定義該區域標準目標的建構檔案。除了標準目標外，區域擁有者也可以新增其他目標。
  • docs/
    • 這個目錄應包含在該領域工作的人員的文件
    • 針對終端開發人員 (或 Fuchsia 的其他領域工作人員) 的文件應位於頂層文件或 SDK 存放區
  • bundles/
    • 這個目錄包含這個區域中的套件目標套件組合。每個區域至少應包含一個 tests 套件，其中包含該區域的單元測試，但可能會包含其他套件。
  • bin/ (非必要)
  • lib/ (非必要)
  • drivers/ (非必要)
  • examples/ (非必要)
  • manifests/
    • 這個目錄包含 Jiri 資訊清單。
    • Jiri 資訊清單檔案會說明執行 jiri update 時會同步的專案組合。詳情請參閱 README。
  • tests/ (選用)
    • 這個目錄包含跨越該區域內多個原始程式碼目錄的整合測試
    • 如果不同區域可在子目錄中進行測試，建議為不同的測試目錄新增 OWNERS 檔案，以便明確指出擁有者。
    • 涵蓋單一二進位檔或程式庫的單元測試，最好與所測試的程式碼一併放置
  • testing/ (選用)
    • 這個目錄包含在這個區域和子區域中編寫測試時實用的公用程式和程式庫。
    • 這個目錄中的目標只能由 testonly 目標依附。
  • third_party/ (選用)
    • 大部分的 third_party 依附元件應位於個別的存放區
    • 只有在下列所有情況下，才在區域中加入 third_party 依附元件：
      • 根據政策規定，程式碼必須位於 third_party 目錄中
      • 您打算分支上游 (即進行重大變更，且不打算整合上游的未來變更)
      • 您為 (a) 不符合上游，且 (b) 不會出現在 Fuchsia 來源樹狀結構中任何其他 third_party 目錄中的程式碼建立新名稱
      • 程式碼為開放原始碼
    • 如要進一步瞭解 第三方原始碼管理 中的 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/

在建構系統中標示為「testonly」的區域中，目標可能會額外依賴該區域和祖系中的 testing 目錄：

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

標準目標

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

  • 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 中的現有目錄
  • 新增至現有區域的新頂層區域或子區域
  • 新增至現有存放區
  • 新增至新存放區 (需要最高層級擁有者核准)