第三方源代码管理

第三方代码是 Fuchsia 代码库的一部分，但不受 Fuchsia 作者的版权保护，也不受 Fuchsia 的许可约束。换句话说，任何不完全归 Fuchsia 作者所有的代码都将作为第三方代码进行管理。

Fuchsia 项目会在 checkout 的 //third_party/ 目录下维护第三方代码依赖项的副本。这也称为“供应商”。供应商确保第三方代码从 Fuchsia 自有源代码库提供，并且提供的修订版已知可与 Fuchsia 签出中的其他代码搭配使用。

添加第三方代码时，请按照以下步骤操作，确保代码符合 Fuchsia 项目政策。

前期准备

所有外部代码都必须通过 Open Source Review Board (OSRB) 流程才能添加到 Fuchsia 平台源代码树中。OSRC 请求获得批准后，请继续执行以下步骤。

特定于语言的指南

如果您要添加 Rust、Go 或 Python 依赖项，请按照以下指南操作：

对于所有其他语言，请继续执行以下步骤。

获取代码

所有外部代码都必须遵循以下 third_party 源代码布局（以 googletest 为例）：

root [fuchsia.googlesource.com/fuchsia]
  third_party/
    googletest/
      src/ [fuchsia.googlesource.com/third_party/github.com/google/googletest]
      BUILD.gn
      OWNERS
      README.fuchsia

//third_party/googletest/src/ 是 Fuchsia 自有镜像代码库的根目录，其中包含 googletest 的上游代码库的副本。（注意：对于 Python 代码库，请将 /src 替换为 /<module_name>，以遵循 Python 的惯例。常见的 Python 工具（例如 pyright）会遵循此惯例。）

//third_party/googletest/ 目录是 fuchsia.git 代码库的一部分。

//third_party/googletest/BUILD.gn 定义了 googletest 库的构建目标。由于此文件属于 fuchsia.git（而非 googletest 代码库），因此可以与依赖于 googletest 的其他 Fuchsia BUILD.gn 文件同步更新。这样可以更轻松地进行 build 重构和其他大规模更改。

将第三方代码调整为适用于 Fuchsia 项目所需的其他文件可能位于 //third_party/googletest（在本例中）下。

添加所有者

每个依赖项都必须有一个关联的 OWNERS 文件。由于它是在 fuchsia.git 中定义的，因此可以包含 Fuchsia 项目中其他位置的其他文件中的所有者。

OWNERS 文件必须在前两行列出两个 Fuchsia 开发者账号，或者包含指向另一个 OWNERS 文件的 file: 指令。这样可以确保对代码的长期维护负责。

OWNERS 通常是使用依赖项的代码的所有者，除非另有说明。

依赖项的 OWNERS 通过以下方式帮助确保 Fuchsia 及其用户的安全： * 在不再需要时移除依赖项 * 在上游修复安全或稳定性 bug 时更新依赖项 * 帮助确保使用该依赖项的 Fuchsia 功能在功能和依赖项随时间推移而发生变化时继续以最佳方式使用该依赖项。

添加了 README.fuchsia

您需要一个 README.fuchsia 文件，其中包含要重复使用的代码所在项目的相关信息。请参阅 README.fuchsia，查看要添加的必填字段列表。

获取评价

所有第三方内容添加和实质性更改（例如重新许可）都需要获得以下人员的批准：

  • 按照 OSRB 审批中的说明进行代码审核。
  • 如果第三方项目对安全至关重要（如 README.fuchsia 中所定义），请在 security-dev@fuchsia.dev 中添加人员来审核更改。

特殊情况

大多数第三方依赖项都可以遵循上述布局。不过，少数依赖项会受到不常见情况的影响，因此管理方式有所不同。

使用奇特的依赖项可能会增加复杂性和维护成本，而这些成本是由第三方代码的直接依赖项产生的。此外，它们还会增加常见的全球维护任务的复杂性，例如：

  • 执行 Git 管理任务。
  • 更新和维护工具链。
  • 通过更新上游来源中存在漏洞的第三方代码，对已披露的安全漏洞做出响应。
  • 重构构建规则，例如强制执行新的编译时检查。

在尝试新路径时，请务必慎重考虑。

将旧版第三方代码迁移到当前布局

将所有现有的 //third_party 代码纳入到上述布局中的工作仍在进行中，欢迎贡献。

如需将旧版第三方代码库迁移到此布局，请按以下步骤操作：

  1. 更新清单。

    1. 将 //third_party/<name> 中现有第三方项目的 path（而非 name）替换为 //third_party/<name>/src，同时保持修订版不变。

    2. 更新 //.gitignore，以便跟踪 //third_party/<name>，但不跟踪 //third_party/<name>/src。

    然后运行 jiri update -local-manifest-project=fuchsia，该命令会将项目移至本地检出目录中的新位置。

  2. 将特定于 Fuchsia 的 BUILD.gn 文件移至 fuchsia.git。

    1. 将 BUILD.gn 文件从 //third_party/<name>/src 复制到 //third_party/<name>（现在是 fuchsia.git 的一部分）。
    2. 在复制的 BUILD.gn 文件中，将对第三方文件路径的引用从 //third_party/<name>/ 格式更新为 //third_party/<name>/src/ 格式。
    3. 将 OWNERS 从 //third_party/<name>/src 复制到 //third_party/<name>，或者创建 OWNERS（如果不存在）。检查 OWNERS 文件，确保其遵循最佳实践。
    4. 将 README.fuchsia 从 //third_party/<name>/src 复制到 //third_party/<name>。查看此文件的内容，并确保元数据正确无误。在极少数情况下，第三方代码库中的第三方代码会发生修改，此类更改会在 README.fuchsia 中列出。进行本地修改通常需要您做出本指南未涵盖的特殊调整。
    5. 检查 //third_party/<name>/src 中是否有任何其他第一方 .gni 文件，并将其也移至 //third_party/<name>。
    6. 更新 //third_party/<name>/BUILD.gn（以及包含源路径的其他文件，例如 .gni 文件），以使用新的源位置 //third_party/<name>/src。这需要更新所有来源，包括目录路径等。

  3. 将 //third_party/<name>/src 转换为镜子。

    将 //third_party/<name>/src 更改为跟踪上游，以便其 git log 中仅包含上游更改。为此，您可以更新清单以引用上游提交哈希。

    示例：http://tqr/427570

  4. 提交并推送您的更改。所有这些更改都可以在单个 CL 中完成。

您可以通过运行 jiri update -local-manifest-project=fuchsia 然后进行构建（例如使用 fx build）在本地验证更改。

深入阅读