第三方源代码管理

第三方代码是 Fuchsia 结账的一部分，但不属于 Fuchsia 作者的，也不受 Fuchsia 许可的约束。换言之，任何代码 并非完全归 Fuchsia 作者所有的内容均作为第三方代码进行管理。

Fuchsia 项目在 //third_party/ 目录。这也称为“ vendoring”。 供应商负责确保第三方代码由 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 文件同步。这个 使构建重构和其他大规模更改变得更轻松。

使第三方代码适应 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. 将特定于 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. 更新集成清单。

    替换现有第三方项目的 path（不是 name），位于 //third_party/<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

深入阅读