第三方源代码管理

第三方代码是 Fuchsia 结账的一部分，但不受 Fuchsia 作者的版权保护，也不受 Fuchsia 的许可的约束。换句话说，任何并非由 Fuchsia 作者拥有的任何代码均作为第三方代码进行管理。

Fuchsia 项目在结账的 //third_party/ 目录下维护第三方代码依赖项的副本。这也称为 vendoring。供应商服务可确保第三方代码由 Fuchsia 拥有的源代码库提供，并在已知适用于 Fuchsia 检出中其他代码的修订版本中提供。

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

前期准备

所有外部代码都必须通过开源审核委员会 (OSRB) 流程才能添加到 Fuchsia 平台源代码树中。一旦 OSRB 请求获得批准后，请继续执行以下步骤。

针对特定语言的指南

如果要添加 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 的惯例。pyright 等常见的 Python 工具会预期此惯例。）

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

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

在本例中，//third_party/googletest 下可能会显示调整第三方代码以适应 Fuchsia 项目所需的其他文件。

添加所有者

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

OWNERS 文件的前两行必须包含两个 Fuchsia 开发者帐号，或者向另一个 OWNERS 文件添加 file: 指令。这样可以确保随着时间的推移对代码维护负责。

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

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

添加 README.fuchsia

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

获取评价

所有第三方新增内容和重大变更（如重新许可）都需要以下签核：

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

特殊情况

大多数第三方依赖项都可以遵循上述布局。但是，少数属于不常见情况的依赖项的管理方式有所不同。

具有外部依赖项会增加复杂性和维护成本，因直接依赖第三方代码而产生的费用会增加。此外，它们还会增加常见的全局维护任务的复杂性，例如：

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

离开鲜有人生的道路时，请谨慎决定。

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

将所有现有的 //third_party 代码部署到上述布局中是正在开发中的，欢迎贡献内容。

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

  1. 将特定于 Fuchsia 的 BUILD.gn 文件移至 //build/secondary。

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

    示例：https://fxrev.dev/622785

  2. 更新集成清单。

    将 //third_party/<name> 中现有第三方项目的 path（而非 name）替换为 //third_party/<name>/src，同时让修订版本保持不变。合并此变更后，Fuchsia build 将改为使用上一步中的 BUILD.gn 文件。

    示例：http://tqr/457911

  3. 将第 1 步中添加的特定于 Fuchsia 的文件移至 //third_party/<name>。

    现在，第三方代码嵌套在 //third_party/<name>/src 下，并且 //third_party/<name> 是 fuchsia.git 的一部分，您可以撤消过渡第 1 步。

    1. 等待集成清单更改合并并完成，然后运行 jiri update。或者，在本地结账步骤中预演上一步中的集成清单更改，然后运行 jiri update -local-manifest。

    2. 将 BUILD.gn 和其他 Fuchsia 专用文件从 //build/secondary/<name> 移至 //third_party/<name>。

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

    示例：https://fxrev.dev/622789

  4. 把 //third_party/<name>/src 变成一面镜子。

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

    示例：http://tqr/427570

深入阅读