源代码布局

搜索源代码

要查看和搜索 Fuchsia 源代码，可使用以下选项：

概览

大多数第一方开源代码都位于“fuchsia.git”中 代码库。此例中的大部分代码 代码库组织为一个递归的 area 树。

区域具有常规的内部和附属结构。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
    • 用于定义规范化目标的 build 文件 区域。除了 规范目标。
  • docs/
    • 此目录应包含该区域工作人员的文档
    • 面向最终开发者（或在其其他 Fuchsia 地区工作的人员）的文档 应位于顶级文档或 SDK 代码库中
  • bundles/
    • 此目录包含此区域中的软件包目标集合。每个区域 应至少包含一个带有针对该区域的单元测试的 tests 软件包，但 可能包含其他套装。
  • bin/（可选）
  • lib/（可选）
  • drivers/（可选）
  • examples/（可选）
  • tests/（可选） <ph type="x-smartling-placeholder">
      </ph>
    • 此目录包含跨多个源代码的集成测试 区域内的目录
    • 如果不同区域的子目录中可以包含测试，建议 为不同测试目录添加 OWNERS 文件，以明确所有权。
    • 最好将涵盖单个二进制文件或库的单元测试放置在 以及他们测试的代码
  • testing/（可选） <ph type="x-smartling-placeholder">
      </ph>
    • 此目录包含用于编写测试的实用程序和库 这个区域和子领域中的资源
    • 只有 testonly 目标才能依赖于此目录中的目标。
  • third_party/（可选） <ph type="x-smartling-placeholder">
      </ph>
    • 大多数第三方依赖项应位于单独的代码库中
    • 仅当满足以下所有条件时，才需要在某个区域中添加 third_party 依赖项： <ph type="x-smartling-placeholder">
        </ph>
      • 根据政策，该代码必须位于 third_party 目录中
      • 您打算向上游创建分支（即进行重大更改，但不打算 整合未来来自上游的更改）
      • 您为代码指定的新名称 (a) 与上游不匹配，并且 (b) 未出现在 Fuchsia 源代码树
      • 代码是开源的
    • 如需详细了解 third_party 源代码布局，请参阅 第三方源代码管理
  • tools/（可选） <ph type="x-smartling-placeholder">
      </ph>
    • 此目录包含该区域提供的命令行工具。这些 通常是可以（或必须）为开发主机构建的内容 而不是 Fuchsia。它们不一定会直接在 但开发者也可以使用它们不一定 不得在 SDK 中发布用于开发应用场景的 但实际上并不适合开发者直接使用， 而不是在这里
    • 此文件应包含以每个工具（或集合）命名的子目录。 使用自然集合名称的相关工具），而不是将所有 将该区域的工具集中到顶部 tools/BUILD.gn 文件中。
  • [subareas]（可选） <ph type="x-smartling-placeholder">
      </ph>
    • 子区域应遵循通用区域模板
    • 不要创建深层嵌套的区域结构（例如，创建三个就够了）

除 枚举目录。

所有者

每个区域和子区域都必须包含一个 OWNERS 文件。目录可能包含 OWNERS，而不被视为区域，例如顶级products 目录或 /src/lib 目录的子目录中。某个目录缺少 OWNERS 文件的所有者被认为与其父目录相同 同一区域

//src/tests 目录是一个例外情况，其中来自不同区域的测试 涵盖系统多个方面（而不只是特定区域）的内容， 预计存留时间因此，每个区域都应为任何资源添加 位于此目录中的测试。

依赖项结构

除了依赖于自身之外，一个区域只能依赖于顶级区域 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 中的区域提升为单独的 代码库通常，在以下情况下，我们应该将一个区域提升为单独的仓库： 区域与系统其余部分之间的接口足够稳定 （需获得顶级所有者的批准）。

新代码可以是：

  • 已添加到 fuchsia.git 中的现有目录
  • 已添加至现有区域的新的顶级区域或子区域
  • 已添加到现有代码库
  • 已添加到新仓库（需要顶级 OWNERS 批准）