Cargo 的本开发周期进展：1.76

2024 年 1 月 3 日 · Ed Page 代表 Cargo 团队

我们希望分享过去 6 周发生的事情，以便更好地让社区了解并参与其中。对于在 1.76 beta 分支之前合并的工作，它们将在 Beta 频道停留 6 周，之后将普遍可用。

这与 This Week in Rust 不同，它更侧重于宏观景象而非单个 PR，并且从更多来源获取信息，例如 Cargo 团队会议和 Zulip。

这是寻找与社区更紧密互动方式的一次实验，我们将看看它的效果以及我们能坚持多久。

已合并

管理 Cargo 的增长

Cargo 团队一直在努力扩展我们的流程，以允许工作空间中的包数量增长

过去一年里，我们在反思一些最近的回归问题时，遇到了一些影响用户的破坏性变更。示例包括：

  • 对 cargo metadata 的输出进行未来不兼容的更新时，没有与第三方 cargo_metadata API 协调 (oli-obk/cargo_metadata#240)
  • 对 cargo-credential 的依赖项产生混淆，导致从 crates.io 构建这些包时出现无法工作的依赖树 (rust-lang/cargo#13004)

一些潜在的改进包括：

作为扩展我们扩展能力的第一步，我们将 Cargo.toml 的 serde 类型 从 Cargo 本身中分离出来 (rust-lang/cargo#12801)。

可能从 cargo 库中分离的其他领域包括：

  • 将 serde 和 CLI 类型移入 cargo-util-schemas
  • 控制台输出
  • 解析和分层合并 .cargo/config.toml
  • 从不同的包源读取（git, path, git registry, sparse registry）
长路径支持

有用户在使用 cargo install --git 时遇到了 Windows 上的路径长度问题 (rust-lang/cargo#13020)，这促使 ChrisDenton 提交了一个 PR，用于 在 cargo 二进制文件中嵌入 Windows 清单文件，仿照 rustc。在该 PR 经过一些探索后，它被合并了，并创建了 rust-lang/cargo#13141 来跟踪剩余的一些工作（这与 rust-lang/cargo#9770 同时进行）。

与 git 交互时，rust-lang/cargo#13020 中有一些关于额外的配置设置以解决问题的说明。

稳定化 cargo metadata 的 id 字段

目前，cargo metadata 包的 id 字段被定义为 不透明的（opaque）。问题在于您无法从输出中获取一个包并将其传递给 cargo <cmd> --package <value>。您可以使用 name 字段，但这在 Cargo.lock 中存在多个不兼容版本时可能会产生歧义。name 是 包 ID 规范（Package ID Specs） 格式的一个子集，大多数 --package 参数都接受这种格式。rust-lang/cargo#12914 提议我们将 id 切换为包 ID 规范，并在 cargo metadata 的输出中将其声明为非不透明的，允许调用者获取 id 并通过 --package 参数传递给 Cargo。

我们确实发现了一个障碍：包 ID 规范有时可能会产生歧义。这在 rust-lang/cargo#12933 中得到了解决。

这正在等待 Cargo 团队的反馈。

-Ztrim-paths

-Ztrim-paths 是一个不稳定的特性，它提供了不同的选项来清理嵌入在最终二进制文件中的路径。这在发布和共享构建产物时，可以在不牺牲调试体验的情况下提高隐私性和可重复性。

-Ztrim-paths 通常可用，并且 weihanglo 一直在推动将其稳定化。最近，他们修复了清理当前工作目录中的包时出现的问题 (rust-lang/cargo#13114)，并添加了端到端测试以确保调试体验不会退步 (rust-lang/cargo#13091 和 rust-lang/cargo#13118)。

还有一些符号尚未清理，例如 macOS 上的 N_SO 和 N_OSO 符号，或在启用分离调试信息（split-debuginfo）时 Linux 上的 DW_AT_comp_dir。这在 rust-lang/rust#117652 中进行跟踪。

清理路径时，我们将路径的起始部分重映射到一个标识符。当前的重映射规则使得配置调试器以重映射到系统上的源代码变得困难。关于替代重映射规则的讨论正在 rust-lang/cargo#13171 中进行。一个重要的考虑因素是用户无论大小端或位宽如何，都能成功在调试器中进行重映射，这对于跨平台调试至关重要。

-Zcheck-cfg

-Zcheck-cfg 是一个不稳定的特性，它会使 rustc 对未定义的条件编译发出警告，例如 #[cfg(unknown)] 或 #[cfg(feature = "unknown")]。

Urgau 一直在 rustc 和 cargo 之间努力完善此功能以便稳定化。最近，他们：

Urgau 希望在 1.77 开发周期开始稳定化讨论。

RFC #3516（公共/私有依赖）

RFC #3516（公共/私有依赖） 已合并，这将帮助用户识别何时在其公共 API 中泄露了其依赖项，从而帮助防止意外的破坏性变更。这需要启用 cargo-features = ["public-dependency"]。相当一部分实现工作是在已被取代的 RFC #1977 中完成的。

linyihai 已介入帮助实现剩余的 Cargo 工作，包括：

其他 Cargo 工作包括：

希望在 2024 Edition 准备好此功能。跟踪 issue 列出了剩余的工作。最大的风险可能是：

用户控制的 Cargo 诊断信息

Cargo 团队对在 Cargo 中添加警告非常谨慎，因为没有像 rustc 的 --allow ... / #[allow(...)] 那样在需要时抑制警告的机制。随着 [lints] 表 的引入，这种情况发生了变化。我们正在 rust-lang/cargo#12235 中跟踪 Cargo 警告控制（以及它可以解锁的 lint）的功能。

第一个里程碑是使 TOML 解析错误匹配 rustc 的错误样式，从

error: failed to parse manifest at `[..]`

Caused by:
  TOML parse error at line 6, column 25
    |
  6 | build = 3
    | ^
  invalid type: integer `3`, expected a boolean or string

到

error: invalid type: integer `3`, expected a boolean or string
--> Cargo.toml:6:25
  |
6 | build = 3
  | ^

与其编写我们自己的模仿 rustc 的错误消息渲染器，不如让 Muscraft 恢复了 annotate-snippets 项目，目的是使其适用于 cargo，然后将 rustc 也迁移到它。他们发布了 annotate-snippets v0.10，并创建了 rust-lang/cargo#13172，用于在解析 Cargo.toml 文件时将其集成到 cargo 中。

我们还需要决定如何处理 rustc 和 cargo 之间的颜色差异。Muscraft 一直在研究 rustc 的颜色是如何选择的，并正在准备一份关于两个程序应该使用什么颜色的提案。

cargo info

我们收到关于 cargo info 命令 的请求已经有将近十年了。hi-rustin，一位经常贡献 Cargo 的贡献者，已经承担起了设计这样一个命令的任务。

您可以通过运行以下命令来尝试它：

$ cargo install cargo-information
$ cargo info clap

欢迎提出想法和提供反馈！请参阅 Issue 跟踪器。

推迟的 RFCs

Cargo 团队正在清理积压的开放 RFC。

RFC #3379（#[cfg] 的 os_version 条件）： 我将参照 RFC 中的摘要

我提议推迟此 RFC。我认为我们都同意这是一个非常有用的功能，但我认为存在一些大问题，特别是关于预构建 std 的版本支持如何工作，它如何与支持目标需求相关联，版本信息如何确定等。主要是，团队中目前没有人有能力负责推动此功能。

RFC #3177（使用 unidiff patch 文件进行 [patch] 依赖）： 我们认为这会非常有用，但有很多细节需要解决，并且团队中没有人能够帮助指导这项工作。借鉴其他团队以及 cargo script eRFC 的经验，我们认为推进此项工作的最佳方式是由某人勾勒出初步提案，然后将其作为一项不稳定功能进行实验实现。此实验将侧重于学习我们需要弄清楚的内容，以便确定 RFC 中应包含什么。

RFC #3287（原生代码覆盖支持）： 我们非常希望改进围绕覆盖率的开发者体验，但不确定该 RFC 是否是正确的方法（例如，rust-lang/cargo#13040 包含一个替代方案）。与 RFC #3177 一样，我们需要进行实验来充实其设计。

RFC #3263（不要将预发布版本视为相互兼容）： 我们完全认识到这是一个问题。例如，Clap 在 3.0 预发布版本中遇到了这个问题，这也是 Clap 停止使用预发布版本的原因。然而，过去一年中该 RFC 中存在许多悬而未决的问题，并且 Cargo 团队中没有人有时间帮助推动这些讨论。一个可行的短期解决方案是使用提议的 Cargo linting 系统 来警告那些在 Cargo.toml 文件中没有使用 = 固定预发布版本需求的用户。作为预发布版本短期测试的替代方案，用户可以 [patch] 依赖项的 git 仓库。对于更广泛地使用不成熟的 API 或行为，Clap 通过以 unstable- 为前缀的功能来暴露它们，这些功能被文档说明为不提供 semver 保证。rust-lang/cargo#10881 提议原生支持不稳定功能。我们认识到这并不能解决当库经历更广泛的破坏性变更时的问题，并且预发布版本仍然有其存在的意义。

行动项： 我们确实需要回去记录实验过程，以便更容易地向人们说明运行实验的期望。

设计讨论

元：2024 Edition

随着 2024 Edition 的窗口即将关闭，我们探讨了是否还应该尝试加入其他内容。

目前，我们计划了

可能将 RFC #3537（MSRV 感知解析器） 与 Edition 绑定。

我们集思广益了其他想法，包括：

禁用默认 features： 我们认为这是更大图景的一部分，为了更容易演进 features，特别是将内置功能置于 feature 之后而不会产生破坏性变更。这本身可能不需要一个 Edition，但我们也讨论过**如果**我们想移除 default-features = false，那将需要一个 Edition。然而，我们不确定这是否我们想要的，我们不想仓促设计，并且在切换之前应该有一个较大的弃用窗口期。

交叉编译 Doctests： 目前，当使用 --target 时，我们会跳过 doctests，而此功能将其更改为开始运行它们。切换到此行为可能会破坏一些用户。在 rust-lang/rust 上测试 -Zdoctest-xcompile 发现使用 --target=armhf-gnu 没有错误，而使用 --target=arm-android 在 std 中有一些错误。从用户意外的角度来看，我们认为人们发现我们静默跳过 doctests 比发现编译错误更令人意外。也许在 Edition 变更时运行（并失败）doctests 会被视为一个 bug 修复。如果我们推进此项工作，这个决定可能不只由我们做出，因为我们还需要稳定其他工具中的标志。讨论正在 zulip 上进行。

让 profile.*.debug=0 隐含 profile.*.strip = "debuginfo"： 当用户使用 debug=0 禁用调试信息时，由于 std 是预构建的，他们仍然会有来自 std 的调试符号。通过在 debug=0 时隐式设置 strip = "debuginfo"，我们将更接近用户实际请求的结果。根据 zulip 讨论串，这可以加快 Linux 上的构建速度并缩小二进制文件大小。在设置了 debug=0 时的缺点是 Mac 上的构建会稍微慢一些，并且回溯信息会较少。从回溯的角度来看，这将使通过 std 的回溯与用户代码保持一致，而用户代码可能占应用程序的大部分。我们认为这可以在没有 Edition 的情况下直接推进，并要求提供更正式的提案，该提案可在 issue 上找到。

将 profile.*.split-debuginfo 设为默认值： 我们之前更改了 Mac 的默认设置 (rust-lang/cargo#9298)，以提高编译速度并减小目标目录大小。如果我们进行此更改，我们意识到它不能与 Edition 绑定，因为 [profile] 是工作空间级别的字段，而 Cargo 只有包的 Edition 概念，没有工作空间的 Edition 概念。有关进一步讨论，请参阅 zulip 讨论串。

[lints] 再议

1.74 引入了 Cargo.toml 中的 [lints]。

随着更多人尝试此功能，主要的关注点包括：

对于最后一点，我们讨论了所有字段的隐式工作空间继承。我们主要关注的问题是这会过于“魔法”，让人们更难理解 Cargo 正在做什么。一个先例是 [profile]。虽然 Cargo 隐式地将 Cargo.toml 叠加在 .cargo/config.toml 之上，但这涉及到配置，这已经有点超出寻常路径，可能不是最好的遵循模式。然而，它也支持 profile 显式地说明它们继承自另一个 profile。我们可以有一个清单级别的 opt-in，用于继承那些未显式设置的字段。根据反馈，我们可以在一个 Edition 上探索更改此默认设置。一个棘手的情况是依赖项。我们不应自动添加所有依赖项。我们可能也不应允许没有源的依赖项（即允许跳过 workspace = true）。但不让依赖项参与进来则会产生不一致性。

讨论 [profile] 这个先例也引出了关于拥有不止一套可继承值集的讨论。我们讨论了一些想法，包括：

  • 拥有命名的字段集，要么全继承要么全不继承（例如，inherits = "public-members"）
  • 拥有可以按字段继承的命名字段（例如，rust-version.workspace = "public-members"）
  • 命名你可以从中继承的其他包，可以是全部或按字段继承
cargo script

cargo script RFC 及其实现的进展已停滞，同时正在解决 关于嵌入清单的 RFC。

目前的提案是

#!/usr/bin/env cargo
```cargo
[dependencies]
clap = { version = "4.2", features = ["derive"] }
```

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

清单嵌入在我们称为代码围栏前置信息（code-fence frontmatter）的东西中，仿照 Markdown。cargo 标识符被称为信息字符串（infostring）。

从长远来看，信息字符串有两个方向可以发展：

  • 父工具（本例中是 Cargo）是否拥有信息字符串的定义权，并允许使用它想要的任何标识符？
  • rustc 是否拥有信息字符串的含义，从而允许 Rust 项目添加其他类型的元数据，而不必担心破坏依赖于自定义标识符的工具？

嵌入式清单语法 RFC 已更新，新增了一个章节，通过建议我们现在硬编码支持 cargo，并将决定留待将来有更多使用场景上下文时做出，从而回避了这场讨论。

我们也认识到，使用三个反引号可能会让用户在尝试将其放入 Markdown 代码围栏时感到困惑，因为用户可能不知道如何转义或忘记转义，从而导致沮丧。

关于嵌入工具元数据的语法的讨论正在 zulip 上进行。

SBOM

供应链安全最近受到了很多关注。其中一个要素是能够追踪二进制文件中包含了哪些内容以及它是如何构建的。这被称为软件物料清单（Software Bill of Materials），简称 SBOM。

此前，arlosi 创建了关于此主题的 Pre-RFC。该 Pre-RFC 继续引起讨论，包括：

  • 列举第三方解决方案的局限性 (链接)
  • 关于 Cargo 的 SBOM 格式的作用，它是应该成为一个中间格式，为集成者提供创建最终 SBOM 所需的信息，还是应该足够自包含，只需转换为所需的格式即可。这影响了诸如以下字段：
    • 作者（可以从清单中提取）
    • 哈希值（伴随着使用哪些算法针对哪些构建产物的问题）
    • 时间戳（不可重现，这是某些 SBOM 用例的要求）

arlosi 计划将反馈整合到 Pre-RFC 中，进行最后一次反馈征集，然后进入完整的 RFC 阶段。

RFC #3537：让 Cargo 在选择依赖项时遵循最低支持的 Rust 版本（MSRV）

Cargo 和 crates.io 生态系统的一个痛点是，当添加一个依赖项时，构建可能会失败，因为它使用了比您的 Rust 版本更新的功能。我们一直在 rust-lang/cargo#9930 中跟踪此问题。从历史上看，我们推迟了这方面的工作，因为我们预计在没有兼容包时出现的错误会比正在解决的问题引起更多的困惑和用户沮丧。我们曾希望 PubGrub 依赖项解析器能够解决此问题，但在我们切换依赖项解析器之前还有很多工作要做。

在 1.74 开发周期中，我们合并了 rust-lang/cargo#12560，它添加了一个永久不稳定实现，以便人们至少可以使用 nightly 版本进行一次性依赖项解析。在 1.76 开发周期之前，我们找到了一种方法，通过只偏好稳定版本来回避解析器错误消息，这在 rust-lang/cargo#12950 中合并了。

这种规避方法被写成了 Pre-RFC: MSRV 感知解析器，这导致了 RFC #3537：让 Cargo 在选择依赖项时遵循最低支持的 Rust 版本（MSRV）。

主要讨论之一是默认情况下是否应该遵守 MSRV，还是需要用户选择加入。在 Cargo 团队会议和办公时间进行了一些讨论后，未来的计划是重新聚焦文档，关注工作流程、我们希望推动的行为（例如避免停滞），以及不同的可能解决方案如何影响工作流程和用户行为。

我们正在等待 RFC 作者将这种新方法整合到 RFC 中。

RFC #3371：CARGO_TARGET_BASE_DIR 支持

RFC #3371 允许用户将所有目标目录移动到一个公共根目录下，而无需用户进行大量记录工作。它早在六月就被提议合并，但被我们忽略了，我们终于能够对其进行讨论。我们澄清了此提案与 按用户缓存 是独立的，并且这两项工作大体上是独立的且有价值的。按用户缓存会减少我们放入目标目录的内容，但工作空间仍然需要一个目标目录来存储不可缓存的构建和最终构建产物。

虽然存在其他解决方案可以满足 CARGO_TARGET_BASE_DIR 的动机，但我们认为 CARGO_TARGET_BASE_DIR 是一个有原则的捷径，可以更快地带来这些好处。

RFC 中提出的一个担忧是人们如何找到他们的目标目录（例如打包构建的 [[bin]]）。如果我们要考虑将工作空间的目标目录切换到中心位置，这将变得更加相关。在 RFC 中，提到了将 target/ 符号链接到目标目录的想法。目前尚不清楚其好处是否大于对不需要它的用户造成的麻烦。用户可以通过 cargo metadata 获取目标目录的位置。稳定化 --out-dir 将绕过大多数访问目标目录的用例。这些可能就足够了。如果不够，也许我们可以探索添加一个配置字段来控制符号链接的创建。

然后我们探索了一下设计空间，从 索引的 dl 字段 中获得了灵感。例如，为 {home} 或 {cargo_home} 设置占位符将使配置更容易在不同账户之间复制。如果我们将 CARGO_TARGET_DIR 扩展为支持占位符，而不是添加 CARGO_TARGET_BASE_DIR，从而允许 CARGO_TARGET_DIR={cargo_home}/target/{manifest_path_hash} 呢？这似乎会大大简化设计。

现在，这项工作又回到了 RFC 作者手中，由他们处理这些反馈并根据需要更新提案。

RFC #3493：cargo update --precise <prerelease>

今天，要使用 预发布版本，用户必须在版本要求中选择加入。RFC #3493 改变了 Cargo 的依赖项解析器，以便用户可以在 Cargo.lock 中选择加入预发布版本。如果用户想要测试预发布依赖项中的回归问题，或者想要提前访问功能但不强制要求（例如性能改进），这将很有用。如果一个包需要预发布版本中的某些内容，例如新的 API，则应该改为在版本要求中指定，这更侧重于 RFC #3263。

既然我们已经在讨论推迟 #3263，我们也讨论了是否应该推迟 #3493。虽然我们想改进预发布版本，但团队中没有人有时间协助指导这项工作，而且该提案将涉及对 Cargo 进行侵入性更改，这很可能不稳定。考虑到我们花时间解决预发布版本问题的程度，不清楚这是否是最重要的。

在我们讨论时，我们意识到有一个可靠的先例可以作为设计基础，那就是撤回（yanked）的包。我们还可以通过建议 semver 包 保留现有的版本匹配逻辑，并在不同的函数名下公开新行为来最小化风险。我们还意识到，此 RFC 是 RFC #3263 的先决条件，以便 Cargo 可以正确地统一预发布版本和常规发布版本的版本要求。

为了方便记录，我们担心这会需要修改 Cargo.lock。如果是这样，那么它可能足够复杂，我们需要先进行实验性实现。然而，在进一步讨论后，我们发现 Cargo.lock 的修改不太可能需要。

我们更新了 RFC，现在正在等待作者完成讨论。

cargo update --precise <yanked>

鉴于 RFC #3493 允许用户通过 --precise 强制使用预发布版本，以及 rust-lang/cargo#12425 对破坏性变更也做了同样的事情，将此概念扩展到撤回的包（yanked packages）似乎是顺理成章的，这样就解决了 rust-lang/cargo#4225。我们认为在这种情况下需要信任用户。用户可能有正当理由访问撤回的包，无论是短期测试还是长期使用并接受风险。我们考虑为此添加一个额外的标志，但预发布版本和破坏性变更不需要标志。对于破坏性变更，该标志用于在 --precise 之外，选择对所有包都选择加入。有可能我们想将此概念扩展到预发布版本和撤回的包。出于谨慎考虑，我们联系了一位前 Cargo 团队成员，以防我们遗漏了什么背景信息，他们给予了批准。

rust-lang/cargo#4225 已标记为 已接受（accepted），我们欢迎人们为此贡献 PR。

其他

其他相关感兴趣的主题

未取得进展的重点领域

这些是 Cargo 团队成员感兴趣的领域，但在本开发周期没有可报告的进展。

准备开发

需要设计和/或实验

计划中

如何提供帮助

如果您有改进 Cargo 的想法，我们建议首先检查 我们的积压工作，然后在 Internals 上探讨您的想法。

如果有一个您希望解决但此处未讨论的特定问题，可以采取以下步骤来帮助推进：

  • 总结现有讨论（例如：更好地支持 Docker 层缓存，Cargo.lock 策略变更，MSRV 感知解析器）
  • 记录其他生态系统的先例，以便我们可以在别人的工作基础上进行构建，并在合适的情况下做出用户熟悉的东西
  • 记录 Cargo 中的相关问题和解决方案，以便我们了解是否正在解决正确抽象层次的问题
  • 基于这些帖子，提出一个考虑到上述信息和 Cargo 兼容性要求的解决方案（示例）

我们可以在 zulip 上为 S-accepted issues 提供指导，并且您可以在 贡献者办公时间（Contributor Office Hours） 与我们实时交流。如果您想帮助解决此处提到的较大项目之一并且刚开始，修复一些 issue 将有助于您熟悉流程和期望，使事情更顺利。如果您想独立解决一些没有导师指导的 issue，那么对您独自完成工作的期望会更高。