第三方源代码管理

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

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

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

前期准备

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

如果依赖项或子依赖项不会在 Fuchsia build 中使用，请在 OSRB 请求中指定这一点，并说明将通过添加到此屏蔽列表来将该依赖项或子依赖项列入 Fuchsia build 的屏蔽列表。 如果要在 Fuchsia 代码库中使用，则会遇到大多数许可问题。

特定语言的指南

如果您要添加 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/ 是 googletest 的Fuchsia 拥有的镜像代码库的根目录，其中包含上游代码库的副本。（注意：对于 Python 代码库，请将 /src 替换为 /<module_name>，以遵循 Python 的惯例。常见的 Python 工具（例如 pyright）会采用此惯例。）

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

//third_party/googletest/BUILD.gn 为 googletest 库定义 build 目标。由于此文件属于 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 审批中的说明，让相关人员审核代码。
    • 如果依赖项或子依赖项不会在 Fuchsia build 中使用，请在 OSRB 请求中指定这一点，并说明将通过添加到此屏蔽列表来将该依赖项或子依赖项列入 Fuchsia build 的屏蔽列表。 如果要在 Fuchsia 代码库中使用，则会遇到大多数许可问题。
  • 如果第三方项目对安全性至关重要（如 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>，或者在 //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）在本地验证更改。

深入阅读