外部 Rust crate

Fuchsia 使用外部 Rust crate。外部 Rust crate //third-party/rust_crates/vendor。这组 crate 包括 列出所需的依赖项 //third_party/rust_crates/Cargo.toml。

通常，添加或更新外部 crate 涉及以下步骤：

  • 计算外部 crate 的依赖项。

  • 请求开源审核委员会 (OSRB) 进行审批。

  • 正在等待获得 OSRB 批准。

  • 上传更改以进行代码审核。

添加外部 crate

如果找不到想要使用的现有 crate， 您可能需要向 Fuchsia 添加一个外部 crate。

如需添加外部 crate，请执行以下操作：

  1. 更改为 Fuchsia 代码库的基本目录。

    例如，如果您的 fuchsia 目录是 ~/fuchsia，请运行以下命令 命令：

      cd ~/fuchsia

  2. 在以下位置添加条目： third_party/rust_crates/Cargo.toml 你要添加的 crate 的 ID。

  3. 运行以下命令下载所需的 crate 并计算 该 crate 的依赖项：

      fx update-rustc-third-party

    fx update-rustc-third-party 会下载 rust_crates/Cargo.toml及其 依赖项，将下载的 crate 放在 vendor 目录中，以及 然后更新 Cargo.toml 和 Cargo.lock。

    您可能需要在 [gn.package.<crate>] 中提供其他配置 部分。Cargo.toml对于使用 build.rs 的 crate 脚本，此配置会替换 构建系统不支持的此配置供 cargo-gnaw，用于从 Cargo.toml 文件生成 GN 规则。 请参阅 cargo-gnaw 的 README 文件 了解详情。

    在本地提交更改后，运行 fx update-rustc-third-party 确保它成功完成了工作 更改。您可以运行 git status 进行确认。

  4. 运行以下命令以执行构建测试：

      fx set core.x64 && fx build

  5. 执行以下操作，请求 OSRB 审批：

    • 创建一个关于以下内容的问题： 开源审核板 (OSRB) 模板。

    • 在该问题中，请执行以下操作：

      • 将 Owner 字段留空。
        • OSRB 团队会定期开会审核问题。 我们会在大约一周后给您答复，请耐心等待。
      • 指定您要添加的所有 crate（无需列出） 之前经过批准的 crate）。包含您要添加的 crate 以及运行 crate 后确定的依赖项 crate fx update-rustc-third-party。
      • 源代码库中有任何未包含的文件 请将问题中的这些文件提交给 OSRB。对于 例如，仅用于测试但已被排除的字体文件 将需要包含在 OSRB 问题中。
      。

  6. 如果您获得 OSRB 批准，请将更改上传到 Gerrit 以供审核。 请在更改中添加 OSRB 问题 ID 编号。

  7. 添加所有者 访问外部 rust crate 目录。您必须获取 Code Review Label +2。

  8. 如果您能够将已获批准的更改 提交队列 (CQ)，提交更改 将该更改合并到 third_party/rust_crates 中。

    如果您无法提交已获批准的更改，请回复 更改 Gerrit 并请求某个代码库所有者提交您的 更改。

    如需详细了解每位贡献者的相关操作 角色，请参阅角色矩阵。

更新外部 crate

如需更新外部 crate，请执行以下操作：

  1. 在 crate 中增加 crate 的补丁号。 third_party/rust_crates/Cargo.toml

    1. 对于传递依赖项（不在根 Cargo.toml 中），您可以改用 cargo +fuchsia update --manifest-path third_party/rust_crates/Cargo.toml --package $crate_name 等命令。

  2. 运行以下命令：

      fx update-rustc-third-party

    您可能需要更新或提供其他配置 位于 Cargo.toml 文件内的 [gn.package.<crate>] 部分中。适用于 crate 使用 build.rs 脚本，此配置会替换该脚本， 编译系统有意不支持该属性。这个 配置由 cargo-gnaw 使用，它会从 Cargo.toml 文件。 如需了解详情，请参阅 cargo-gnaw 的 README 文件。

    在本地提交更改后，运行 fx update-rustc-third-party 确保它成功完成了工作 更改。您可以运行 git status 进行确认。

  3. 运行以下命令以执行构建测试：

      fx set core.x64 && fx build

  4. 检查许可或依赖项方面的变化。如果有 必须完成 OSRB 审批流程。 执行以下操作，请求 OSRB 审批：

    • 创建一个关于以下内容的问题： 开源审核板 (OSRB) 模板。

    • 在该问题中，请执行以下操作：

      • 将 Owner 字段留空。
        • OSRB 团队会定期开会审核问题。 我们会在大约一周后给您答复，请耐心等待。
      • 指定要添加的所有 crate。包含 crate 以及您要添加的依赖项 crate 正在运行fx update-rustc-third-party。
      • 源代码库中有任何未包含的文件 请将问题中的这些文件提交给 OSRB。对于 例如，仅用于测试但已被排除的字体文件 将需要包含在 OSRB 问题中。
      。

  5. 针对修改后的 crate 更新 OWNERS 文件。请参阅 OWNERS 文件部分，详细了解如何更新 OWNERS 文件。

  6. 如果您/获得 OSRB 批准，请将更改内容上传到 Gerrit。请在更改中添加 OSRB 问题 ID 编号。

  7. 如果没有更改许可或依赖关系，您可以上传更改的内容 以供审核，而不通过 OSRB 审批流程。

添加新镜像

在主动为上游仓库贡献代码时，或 维护 Fuchsia 代码库的长期分支， 使用完整的 Git 代码库（而不是 Cargo 的供应商工具）导入 crate。 虽然这种方法很有用，但与 默认流程，因此应谨慎使用。

  1. 请在 fuchsia.googlesource.com 上请求添加镜像。
  2. 将镜像添加到 Rust 运行时的 Jiri 清单中。
  3. 将 crate 的补丁部分添加到工作区。
  4. 运行更新脚本。

导入 crate 中的文件子集

在某些情况下，您可能只想导入 crate 中的文件子集。对于 例如， 不符合 Fuchsia 许可要求的外部存储区。 下面是一个示例 发生此问题的 OSRB 审核。

为此，您需要将 crate 的文件添加到 /third_party/rust_crates/forks。

  1. 按照添加外部 crate 的说明进行操作。
  2. 运行fx update-rustc-third-party后，将下载的副本 从 /third_party/rust_crates/vendor/<my_crate> 到 crate /third_party/rust_crates/forks/<my_crate>。
  3. 根据需要对导入的文件进行更改。

  4. 向 [patch.crates-io] /third_party/rust_crates/Cargo.toml 指向您的新 crate：

    [patch.crates-io]
...
my_crate = { path = "forks/<my_crate>" }
...

  5. 重新运行 fx update-rustc-third-party 和 fx build。

  6. 添加一个 /third_party/rust_crates/forks/<my_crate>/README.fuchsia 文件，用于 与其他 crate 的格式匹配，README.fuchsia。请参阅 /third_party/rust_crates/forks/README.md的用途 应包含的内容

Unicode crate

如果项目需要导入新的外部 crate 进行处理 与 Unicode 和国际化相关的功能，更推荐使用 UNIC 项目（如果有）。

获得豁免的非 UNIC crate

以下非 UNIC crate 已由供应商提供，因此不受此要求：

  • unicode-bidi
  • unicode-normalization
  • unicode-segmentation
  • unicode-width
  • unicode-xid

标准化的理由

与其他 crate 相比，UNIC crate 具有明显的优势：

  • UNIC crate 在单个代码库中开发，具有共享的通用代码和 单一版本方案。

    • 独立开发的 crate 没有相同的发布时间表， 或遵守任何特定版本的 Unicode 标准。

  • UNIC crate 根据一组一致的 Unicode 数据文件生成。

    • 每个独立的 crate 都使用任意版本和 数据。例如，不同的 crate 可能有不同的假设 是否分配特定码位及其属性 等等

  • UNIC 项目旨在提供全面的功能覆盖，就像 ICU（适用于 Rust）。如果项目 如果成功了，对不相关的 Unicode crate 的依赖关系应该是 会随着时间的推移而降低

OWNERS 的文件

系统会为所有外部 Rust crate 维护 OWNERS 文件， 指明由谁负责审核和更新。这些文件是 结合使用 build 图元数据和显式 替换文件。

update-rustc-third-party 工具会尽力更新这些文件 但可能会出错。update-3p-owners 直接从我们的 build 中重新生成 OWNERS 文件， 图表。

运行该工具

该工具会发现哪些构建目标依赖于给定 crate，这意味着 需要最大“厨房接收器”完成后产生的元数据build：

  1. 运行 fx set core.x64 --with //bundles/buildbot/core --with //bundles/kitchen_sink
  2. 运行 fx update-3p-owners --rust-metadata <FUCHSIA_BUILD_DIR>/rustlang/3p-crates-metadata.json。

手动更新“OWNERS”

供应商的第三方 crate 的 OWNERS 文件基于以下两个主要部分： 来源：

  1. 依赖于第三方 Rust crate 的目标具有其 OWNERS 文件 针对它们所依赖的 crate 导入 OWNERS。例如，如果 src/lib/foo 等目标依赖于 bar crate，然后是 OWNERS 文件 的 bar crate 将包含 src/lib/foo/OWNERS。
  2. 依赖于其他第三方 Rust crate 导入的第三方 Rust crate 将其依赖项的 OWNERS 文件转换为其自己的 OWNERS 文件。例如，如果 bar crate 依赖于 baz crate，然后是 bar crate 的 OWNERS 文件。 将包含 third_party/rust_crates/vendor/bar-1.0.0/OWNERS。

对于现有 crate 的版本递增，通常只需更新 include 语句添加到更新后的 crate 的最新版本。

添加替换项

有些 crate 的用户数超出了可以依赖的级别 （请参阅旁观者效应）。还有一些代码则实现特定于 安全领域，我们更希望由一个特定团队来负责 ，申请对代码进行审核。

在这些情况下，请使用以下代码向 //third_party/owners.toml 添加一个条目： 要引用的其他 OWNERS 文件的路径，然后重新运行该工具。 这会将反向依赖项元数据所有权替换为 路径。

更新频率

Rust on Fuchsia 团队目前负责运行 定期更新工具请参阅 https://fxbug.dev/42152910 跟踪自动更新 OWNERS 文件的过程。

在本地替换

如果您是向上游贡献代码，替换第三方 crate 会很有用 并希望运行树内构建或测试。这可以通过以下方法实现： 步骤。

  1. 克隆（或用符号链接）下方的上游仓库 third_party/rust_crates/forks/<my_crate>。
  2. 将替换项添加到 [patch.crates-io] 部分中的 third_party/rust_crates/Cargo.toml。
[patch.crates-io]
my_crate = { path = "forks/<my_crate>" }
  1. 您必须确保 crate 的 Cargo.toml 下的版本与 third_party/rust_crates/Cargo.toml 中对该 crate 的所有引用。
  2. 运行 fx update-rustc-third-party。

问题排查

配置已损坏

运行 fx update-rustc-third-party 后，如果您遇到类似如下的错误 ：

Generating GN file from /$HOME/fuchsia/third_party/rust_crates/Cargo.toml
Error: GNaw config exists for crates that were not found in the Cargo
build graph:

library crate, package handlebars version 2.0.0-beta.2
library crate, package core-foundation-sys version 0.7.0
library crate, package pulldown-cmark version 0.6.0
library crate, package nix version 0.18.0

您可以通过在 .cargo/config 中注释掉紫红色目标来解决此问题：

[build]
...
target = "x86_64-unknown-fuchsia"

评论之后，新名称将变为：

[build]
...
# target = "x86_64-unknown-fuchsia"

我们已在上游跟踪此问题。