不稳定的功能

实验性的 Cargo 功能仅在 nightly 频道上可用。我们鼓励您尝试这些功能，看看它们是否满足您的需求，以及是否存在任何问题。查看下面列出的链接跟踪问题以获取有关该功能的更多信息，如果您希望获得未来的更新，请单击 GitHub 订阅按钮。

一段时间后，如果该功能没有任何重大问题，则可以将其稳定化，这将使其在当前 nightly 版本到达稳定频道（6 到 12 周）后在稳定版上可用。

根据功能的工作方式，可以通过三种不同的方式启用不稳定的功能

Cargo.toml 中的新语法需要在 Cargo.toml 顶部的任何表之前使用 cargo-features 键。例如

# This specifies which new Cargo.toml features are enabled.
cargo-features = ["test-dummy-unstable"]

[package]
name = "my-package"
version = "0.1.0"
im-a-teapot = true  # This is a new option enabled by test-dummy-unstable.

新的命令行标志、选项和子命令需要同时包含 -Z unstable-options CLI 选项。例如，新的 --out-dir 选项仅在 nightly 版本上可用

cargo +nightly build --out-dir=out -Z unstable-options
-Z 命令行标志用于启用可能没有接口、尚未设计接口或影响 Cargo 多个部分的更复杂功能的新功能。例如，可以使用以下命令启用 mtime-on-use 功能

cargo +nightly build -Z mtime-on-use

运行 cargo -Z help 以查看可用标志列表。

可以使用 -Z 标志配置的任何内容也可以在 cargo 配置文件 (.cargo/config.toml) 的 unstable 表中设置。例如
```
[unstable]
mtime-on-use = true
build-std = ["core", "alloc"]
```

下面描述的每个新功能都应说明如何使用它。有关最新的 nightly 版本，请参阅此页面的 nightly 版本。

不稳定功能列表

不稳定特定功能
- -Z allow-features — 提供一种限制使用哪些不稳定功能的方法。
构建脚本和链接
- Metabuild — 提供声明性构建脚本。
解析器和功能
- no-index-update — 阻止 cargo 更新索引缓存。
- avoid-dev-deps — 阻止解析器在解析期间包含开发依赖项。
- minimal-versions — 强制解析器使用最低兼容版本而不是最高版本。
- direct-minimal-versions — 强制解析器使用最低兼容版本而不是最高版本。
- public-dependency — 允许将依赖项分类为公共或私有。
- msrv-policy — 支持 MSRV 的解析器和版本选择
- precise-pre-release — 允许使用 update --precise 选择预发布版本
输出行为
- out-dir — 添加一个目录，用于将工件复制到该目录。
- 不同的二进制文件名 — 为构建的二进制文件分配一个与箱子名称不同的名称。
编译行为
- mtime-on-use — 每次使用依赖项时都会更新其上次修改时间戳，以提供一种删除未使用工件的机制。
- doctest-xcompile — 支持使用 --target 标志运行 doctest。
- build-std — 构建标准库，而不是使用预构建的二进制文件。
- build-std-features — 设置要与标准库一起使用的功能。
- binary-dep-depinfo — 使 dep-info 文件跟踪二进制依赖项。
- panic-abort-tests — 允许使用“中止”紧急策略运行测试。
- check-cfg — 在编译时验证 cfg 表达式。
- host-config — 允许为主机构建目标设置类似 [target] 的配置设置。
- target-applies-to-host — 更改是否将某些标志传递给主机构建目标。
- gc — 全局缓存垃圾回收。
- open-namespaces — 允许多个包参与同一个 API 命名空间
rustdoc
- rustdoc-map — 提供文档映射，以链接到外部网站，例如 docs.rs。
- scrape-examples — 显示文档中的示例。
- output-format — 允许以实验性的 JSON 格式输出文档。
Cargo.toml 扩展
- 配置文件 rustflags 选项 — 直接传递给 rustc。
- codegen-backend — 选择 rustc 使用的代码生成后端。
- per-package-target — 为每个包设置要使用的 --target。
- 工件依赖项 — 允许将构建工件包含到其他构建工件中，并为不同的目标构建它们。
- 2024 版 — 添加对 2024 版的支持。
- 配置文件 trim-paths 选项 — 控制构建输出中文件路径的清理。
信息和元数据
- 构建计划 — 以 JSON 格式输出有关将运行哪些命令的信息。
- 单元图 — 为 Cargo 的内部图结构输出 JSON。
- cargo rustc --print — 使用 --print 调用 rustc 以显示来自 rustc 的信息。
配置
- config-include — 添加配置文件包含其他文件的功能。
- cargo config — 添加一个用于查看配置文件的新子命令。
注册表
- publish-timeout — 控制上传包和在索引中可用之间的超时
- asymmetric-token — 添加对使用非对称加密的身份验证令牌的支持（cargo:paseto 提供程序）。
其他
- gitoxide — 使用 gitoxide 而不是 git2 来执行一组操作。
- script — 启用对单文件 .rs 包的支持。

allow-features

这个永久不稳定的标志使得只能使用列出的不稳定功能集。具体来说，如果您传递 -Zallow-features=foo,bar，您将能够继续将 -Zfoo 和 -Zbar 传递给 cargo，但您将无法传递 -Zbaz。您可以传递一个空字符串 (-Zallow-features=) 来禁用所有不稳定功能。

-Zallow-features 还限制了可以传递给 Cargo.toml 中 cargo-features 条目的不稳定功能。例如，如果您想允许

cargo-features = ["test-dummy-unstable"]

其中 test-dummy-unstable 不稳定，则 -Zallow-features= 也会禁用该功能，而 -Zallow-features=test-dummy-unstable 则允许该功能。

传递给 cargo 的 -Zallow-features 的功能列表也会传递给 cargo 最终调用的任何 Rust 工具（如 rustc 或 rustdoc）。因此，如果您运行 cargo -Zallow-features=，则无法使用任何不稳定的 Cargo *或* Rust 功能。

no-index-update

原始问题：#3479
跟踪问题：#7404

-Z no-index-update 标志确保 Cargo 不会尝试更新注册表索引。这适用于 Crater 等发出许多 Cargo 命令的工具，并且您希望避免每次更新索引时的网络延迟。

-Z mtime-on-use 标志是一个实验，让 Cargo 更新已使用文件的 mtime，以便 cargo-sweep 等工具更容易检测哪些文件已过时。对于许多工作流程，需要在 *所有* 调用 cargo 时设置此选项。为了使这更实用，在 .cargo/config.toml 或相应的 ENV 变量中设置 unstable.mtime_on_use 标志会将 -Z mtime-on-use 应用于 nightly cargo 的所有调用。（稳定版会忽略 config 标志）

avoid-dev-deps

原始问题：#4988
跟踪问题：#5133

目前，在运行 cargo install 或 cargo build 等命令时，Cargo 需要下载开发依赖项，即使它们没有被使用。-Z avoid-dev-deps 标志允许 Cargo 在不需要开发依赖项时避免下载它们。如果跳过开发依赖项，则不会生成 Cargo.lock 文件。

minimal-versions

原始问题：#4100
跟踪问题：#5657

注意：不建议使用此功能。因为它对所有传递依赖项强制执行最低版本，所以它的用处有限，因为并非所有外部依赖项都声明了正确的最低版本界限。将来打算将其更改为仅对直接依赖项强制执行最低版本。

生成 Cargo.lock 文件时，-Z minimal-versions 标志会将依赖项解析为满足要求的最低 SemVer 版本（而不是最高版本）。

此标志的预期用例是在持续集成期间检查 Cargo.toml 中指定的版本是否正确反映了您实际使用的最低版本。也就是说，如果 Cargo.toml 说 foo = "1.0.0"，那么您就不会意外地依赖于仅在 foo 1.5.0 中添加的功能。

direct-minimal-versions

原始问题：#4100
跟踪问题：#5657

生成 Cargo.lock 文件时，-Z direct-minimal-versions 标志会将依赖项解析为仅针对直接依赖项满足要求的最低 SemVer 版本（而不是最高版本）。

间接依赖项的解析方式与往常一样，因此不会被其最低版本验证所阻塞。

out-dir

原始问题：#4875
跟踪问题：#6790

此功能允许您指定在构建工件后将其复制到的目录。通常，工件只写入 target/release 或 target/debug 目录。但是，确定确切的文件名可能很棘手，因为您需要解析 JSON 输出。--out-dir 标志可以更容易地以可预测的方式访问工件。请注意，工件是复制的，因此原始文件仍在 target 目录中。示例

cargo +nightly build --out-dir=out -Z unstable-options

这也可以在 .cargo/config.toml 文件中指定。

[build]
out-dir = "out"

doctest-xcompile

跟踪问题：#7040
跟踪 Rustc 问题：#64245

此标志在传递目标时更改 cargo test 处理文档测试的行为。目前，如果传递的目标与主机不同，cargo 将简单地跳过测试文档测试。如果存在此标志，cargo 将继续正常运行，将测试传递给 doctest，同时还传递 --target 选项，以及启用 -Zunstable-features --enable-per-target-ignores 并传递来自 .cargo/config.toml 的信息。有关更多信息，请参阅 rustc 问题。

cargo test --target foo -Zdoctest-xcompile

构建计划

跟踪问题：#5579

build 命令的 --build-plan 参数将输出包含有关将运行哪些命令的信息的 JSON，而无需实际执行任何操作。这在与其他构建工具集成时非常有用。示例

cargo +nightly build --build-plan -Z unstable-options

元构建

跟踪问题：rust-lang/rust#49803
RFC：#2196

元构建是一个用于声明式构建脚本的功能。您无需编写 build.rs 脚本，而是在 Cargo.toml 的 metabuild 键中指定构建依赖项列表。系统会自动生成一个构建脚本，按顺序运行每个构建依赖项。然后，元构建包可以从 Cargo.toml 读取元数据以指定其行为。

在 Cargo.toml 的顶部包含 cargo-features，在 package 中包含 metabuild 键，在 build-dependencies 中列出依赖项，并在 package.metadata 下添加元构建包所需的任何元数据。示例

cargo-features = ["metabuild"]

[package]
name = "mypackage"
version = "0.0.1"
metabuild = ["foo", "bar"]

[build-dependencies]
foo = "1.0"
bar = "1.0"

[package.metadata.foo]
extra-info = "qwerty"

元构建包应该有一个名为 metabuild 的公共函数，该函数执行与常规 build.rs 脚本相同的操作。

public-dependency

跟踪问题：#44663

“public-dependency”功能允许将依赖项标记为“公共”或“私有”。启用此功能后，会将其他信息传递给 rustc，以允许 exported_private_dependencies lint 正常运行。

要启用此功能，您可以使用 -Zpublic-dependency

cargo +nightly run -Zpublic-dependency

或 [unstable] 表，例如：

# .cargo/config.toml
[unstable]
public-dependency = true

public-dependency 也可以在 cargo-features 中启用，**但这已被弃用，并将很快被删除**。

cargo-features = ["public-dependency"]

[dependencies]
my_dep = { version = "1.2.3", public = true }
private_dep = "2.0.0" # Will be 'private' by default

文档更新

对于工作区的“依赖项表”部分，在 workspace.dependencies 的不受支持字段中包含 public

msrv-policy

#9930（MSRV 感知解析器）

在 RFC 2495 下，为 MSRV 感知 cargo 功能提供全面的不稳定功能。

MSRV 感知 cargo add

这在 1.79 版本的 #13608 中已稳定。

MSRV 感知解析器

-Zmsrv-policy 允许访问可以通过以下方式启用的 MSRV 感知解析器

resolver.something-like-precedence 配置字段
workspace.resolver = "3" / package.resolver = "3"
package.edition = "2024"（仅限工作区根目录）

解析器将优先选择 package.rust-version 与您项目的 MSRV 相同或更旧的依赖项。您项目的 MSRV 是通过获取工作区成员中设置的最低 package.rust-version 来确定的。如果没有设置，将使用您的工具链版本，目的是从 rustup 的 rust-toolchain.toml 中获取版本（如果存在）。

`resolver.something-like-precedence`

类型：字符串
默认值：“something-like-maximum”
环境：CARGO_RESOLVER_SOMETHING_LIKE_PRECEDENCE

选择解析依赖项时应使用的策略。值包括

something-like-maximum：优先选择包的最高兼容版本
something-like-rust-version：优先选择与您项目的 Rust 版本兼容的包版本

可以使用以下方法覆盖

--ignore-rust-version CLI 选项
将依赖项的版本要求设置得太高
使用 --precise 为 cargo update 指定版本

precise-pre-release

跟踪问题：#13290
RFC：#3493

precise-pre-release 功能允许使用 update --precise 选择预发布版本，即使项目的 Cargo.toml 中未指定预发布版本。

以这个 Cargo.toml 为例。

[dependencies]
my-dependency = "0.1.1"

可以使用 update -Zunstable-options my-dependency --precise 0.1.2-pre.0 将 my-dependency 更新为预发布版本。这是因为 0.1.2-pre.0 被认为与 0.1.1 兼容。无法以相同的方式从 0.1.1 升级到 0.2.0-pre.0。

build-std

跟踪存储库：https://github.com/rust-lang/wg-cargo-std-aware

build-std 特性使 Cargo 能够在 crate 图编译过程中编译标准库本身。此特性在过去也被称为“std-aware Cargo”。此特性仍处于开发的非常早期阶段，并且也是 Cargo 中一项可能的大规模功能添加。即使以目前存在的最小形式，这也是一项需要记录的非常大的功能，因此如果您有兴趣了解最新信息，您需要关注跟踪仓库及其问题集。

今天实现的功能隐藏在一个名为 -Z build-std 的标志后面。此标志指示 Cargo 应使用与主构建本身相同的配置文件从源代码编译标准库。请注意，为此您需要准备好标准库的源代码，并且此时唯一支持的方法是添加 rust-src rust rustup 组件

$ rustup component add rust-src --toolchain nightly

今天还需要将 -Z build-std 标志与 --target 标志结合使用。请注意，您不必进行交叉编译，您只需以一种或另一种形式传递 --target。

用法如下所示

$ cargo new foo
$ cd foo
$ cargo +nightly run -Z build-std --target x86_64-unknown-linux-gnu
   Compiling core v0.0.0 (...)
   ...
   Compiling foo v0.1.0 (...)
    Finished dev [unoptimized + debuginfo] target(s) in 21.00s
     Running `target/x86_64-unknown-linux-gnu/debug/foo`
Hello, world!

在这里，我们重新编译了调试模式下带有调试断言的标准库（如 src/main.rs 的编译方式），最后将所有内容链接在一起。

使用 -Z build-std 将隐式编译稳定的 crate core、std、alloc 和 proc_macro。如果您正在使用 cargo test，它还将编译 test crate。如果您使用的环境不支持其中一些 crate，那么您也可以将参数传递给 -Zbuild-std

$ cargo +nightly build -Z build-std=core,alloc

这里的值是用逗号分隔的要构建的标准库 crate 列表。

要求

总而言之，今天使用 -Z build-std 的要求列表是

您必须通过 rustup component add rust-src 安装 libstd 的源代码
您必须传递 --target
您必须同时使用 nightly Cargo 和 nightly rustc
必须将 -Z build-std 标志传递给所有 cargo 调用。

报告错误和提供帮助

-Z build-std 功能处于开发的非常早期阶段！Cargo 的这个功能历史悠久，范围非常广，这仅仅是个开始。如果您想报告错误，请将其报告给

Cargo — https://github.com/rust-lang/cargo/issues/new — 用于实现错误
跟踪仓库 — https://github.com/rust-lang/wg-cargo-std-aware/issues/new — 用于更大的设计问题。

此外，如果您想查看尚未实现的功能和/或某些功能的运行方式与您的预期不符，请随时查看跟踪仓库的问题跟踪器，如果它不存在，请提交新问题！

build-std-features

跟踪存储库：https://github.com/rust-lang/wg-cargo-std-aware

此标志是 -Zbuild-std 功能标志的同级标志。这将在构建标准库时配置为标准库本身启用的功能。目前默认启用的功能是 backtrace 和 panic-unwind。此标志需要一个逗号分隔的列表，如果提供，将覆盖已启用的功能的默认列表。

binary-dep-depinfo

跟踪 rustc 问题：#63012

-Z binary-dep-depinfo 标志使 Cargo 将相同的标志转发给 rustc，这将导致 rustc 在“dep info”文件中包含所有二进制依赖项的路径（扩展名为 .d）。然后 Cargo 使用该信息进行变更检测（如果任何二进制依赖项发生变化，则将重建 crate）。主要用例是构建编译器本身，它对标准库具有隐式依赖关系，否则这些依赖关系将无法跟踪以进行变更检测。

panic-abort-tests

跟踪问题：#67650
原始拉取请求：#7460

-Z panic-abort-tests 标志将启用 nightly 支持以使用 -Cpanic=abort 编译测试工具 crate。如果没有此标志，Cargo 将使用 -Cpanic=unwind 编译测试及其依赖的所有内容，因为这是 test-the-crate 知道的唯一操作方式。但是，从 rust-lang/rust#64158 开始，test crate 支持 -C panic=abort，每个进程进行一次测试，并且可以帮助避免多次编译 crate 图。

目前尚不清楚此功能将如何在 Cargo 中稳定下来，但我们希望以某种方式稳定它！

config-include

跟踪问题：#7723

此功能需要 -Zconfig-include 命令行选项。

配置文件中的 include 键可用于加载另一个配置文件。它接受一个字符串作为相对于配置文件的另一个文件的路径，或一个配置文件路径数组。仅接受以 .toml 结尾的路径。

# a path ending with `.toml`
include = "path/to/mordor.toml"

# or an array of paths
include = ["frodo.toml", "samwise.toml"]

与其他配置值不同，include 键的合并行为不同。当配置文件包含 include 键时

首先从 include 路径加载配置值。
- 如果 include 键的值是一个路径数组，则从左到右加载和合并每个路径的配置值。
- 如果来自 include 路径的配置值也包含 include 键，则递归执行此步骤。
然后，将配置文件自身的配置值合并到来自 include 路径的配置之上。

target-applies-to-host

原始拉取请求：#9322
跟踪问题：#9453

历史上，Cargo 对于环境变量和 [target] 中的 linker 和 rustflags 配置选项是否适用于构建脚本、插件和其他始终为主机平台构建的工件的行为一直有些不一致。当未传递 --target 时，Cargo 尊重构建脚本的 linker 和 rustflags 与所有其他编译工件相同。但是，当传递 --target 时，Cargo 尊重 [target.<host triple>] 中的 linker，并且不获取任何 rustflags 配置。这种双重行为令人困惑，但也使得难以正确配置主机三元组和目标三元组恰好相同但应以不同方式配置要在构建主机上运行的工件的构建。

-Ztarget-applies-to-host 启用 Cargo 配置文件中的顶级 target-applies-to-host 设置，允许用户选择这些属性的不同（且更一致）行为。当 target-applies-to-host 在配置文件中未设置或设置为 true 时，将保留现有的 Cargo 行为（尽管请参阅 -Zhost-config，它更改了该默认值）。当它设置为 false 时，无论是否将 --target 传递给 Cargo，都不会为主机工件尊重 [target.<host triple>]、RUSTFLAGS 或 [build] 中的任何选项。要自定义要在主机上运行的工件，请使用 [host]（host-config）。

将来，target-applies-to-host 最终可能会默认为 false，以提供更合理和一致的默认行为。

# config.toml
target-applies-to-host = false

cargo +nightly -Ztarget-applies-to-host build --target x86_64-unknown-linux-gnu

host-config

原始拉取请求：#9322
跟踪问题：#9452

配置文件中的 host 键可用于将标志传递给主机构建目标，例如在交叉编译时必须在主机系统而不是目标系统上运行的构建脚本。它支持通用表和主机架构特定表。匹配的主机架构表优先于通用主机表。

它需要设置 -Zhost-config 和 -Ztarget-applies-to-host 命令行选项，并在 Cargo 配置文件中设置 target-applies-to-host = false。

# config.toml
[host]
linker = "/path/to/host/linker"
[host.x86_64-unknown-linux-gnu]
linker = "/path/to/host/arch/linker"
rustflags = ["-Clink-arg=--verbose"]
[target.x86_64-unknown-linux-gnu]
linker = "/path/to/target/linker"

在 x86_64-unknown-linux-gnu 主机上构建时，上面的通用 host 表将被完全忽略，因为 host.x86_64-unknown-linux-gnu 表优先。

设置 -Zhost-config 会将 target-applies-to-host 的默认值从 true 更改为 false。

cargo +nightly -Ztarget-applies-to-host -Zhost-config build --target x86_64-unknown-linux-gnu

unit-graph

跟踪问题：#8002

--unit-graph 标志可以传递给任何构建命令（build、check、run、test、bench、doc 等），以向 stdout 发出一个表示 Cargo 内部单元图的 JSON 对象。实际上没有构建任何东西，并且命令在打印后立即返回。每个“单元”对应于编译器的一次执行。这些对象还包括每个单元依赖于哪个单元。

cargo +nightly build --unit-graph -Z unstable-options

此结构提供了 Cargo 所看到的依赖关系的更完整视图。特别是，“features”字段支持新的功能解析器，其中可以使用不同的功能多次构建依赖项。cargo metadata 从根本上无法表示不同依赖类型之间特征的关系，并且特征现在取决于运行哪个命令以及选择了哪些包和目标。此外，它还可以提供有关包内依赖项的详细信息，例如构建脚本或测试。

以下是 JSON 结构的描述

{
  /* Version of the JSON output structure. If any backwards incompatible
     changes are made, this value will be increased.
  */
  "version": 1,
  /* Array of all build units. */
  "units": [
    {
      /* An opaque string which indicates the package.
         Information about the package can be obtained from `cargo metadata`.
      */
      "pkg_id": "my-package 0.1.0 (path+file:///path/to/my-package)",
      /* The Cargo target. See the `cargo metadata` documentation for more
         information about these fields.
         https://doc.rust-lang.net.cn/cargo/commands/cargo-metadata.html
      */
      "target": {
        "kind": ["lib"],
        "crate_types": ["lib"],
        "name": "my-package",
        "src_path": "/path/to/my-package/src/lib.rs",
        "edition": "2018",
        "test": true,
        "doctest": true
      },
      /* The profile settings for this unit.
         These values may not match the profile defined in the manifest.
         Units can use modified profile settings. For example, the "panic"
         setting can be overridden for tests to force it to "unwind".
      */
      "profile": {
        /* The profile name these settings are derived from. */
        "name": "dev",
        /* The optimization level as a string. */
        "opt_level": "0",
        /* The LTO setting as a string. */
        "lto": "false",
        /* The codegen units as an integer.
           `null` if it should use the compiler's default.
        */
        "codegen_units": null,
        /* The debug information level as an integer.
           `null` if it should use the compiler's default (0).
        */
        "debuginfo": 2,
        /* Whether or not debug-assertions are enabled. */
        "debug_assertions": true,
        /* Whether or not overflow-checks are enabled. */
        "overflow_checks": true,
        /* Whether or not rpath is enabled. */
        "rpath": false,
        /* Whether or not incremental is enabled. */
        "incremental": true,
        /* The panic strategy, "unwind" or "abort". */
        "panic": "unwind"
      },
      /* Which platform this target is being built for.
         A value of `null` indicates it is for the host.
         Otherwise it is a string of the target triple (such as
         "x86_64-unknown-linux-gnu").
      */
      "platform": null,
      /* The "mode" for this unit. Valid values:

         * "test" --- Build using `rustc` as a test.
         * "build" --- Build using `rustc`.
         * "check" --- Build using `rustc` in "check" mode.
         * "doc" --- Build using `rustdoc`.
         * "doctest" --- Test using `rustdoc`.
         * "run-custom-build" --- Represents the execution of a build script.
      */
      "mode": "build",
      /* Array of features enabled on this unit as strings. */
      "features": ["somefeat"],
      /* Whether or not this is a standard-library unit,
         part of the unstable build-std feature.
         If not set, treat as `false`.
      */
      "is_std": false,
      /* Array of dependencies of this unit. */
      "dependencies": [
        {
          /* Index in the "units" array for the dependency. */
          "index": 1,
          /* The name that this dependency will be referred as. */
          "extern_crate_name": "unicode_xid",
          /* Whether or not this dependency is "public",
             part of the unstable public-dependency feature.
             If not set, the public-dependency feature is not enabled.
          */
          "public": false,
          /* Whether or not this dependency is injected into the prelude,
             currently used by the build-std feature.
             If not set, treat as `false`.
          */
          "noprelude": false
        }
      ]
    },
    // ...
  ],
  /* Array of indices in the "units" array that are the "roots" of the
     dependency graph.
  */
  "roots": [0],
}

配置文件 `rustflags` 选项

原始问题：rust-lang/cargo#7878
跟踪问题：rust-lang/cargo#10271

此功能在 [profile] 部分提供了一个新选项，用于指定直接传递给 rustc 的标志。可以像这样启用

cargo-features = ["profile-rustflags"]

[package]
# ...

[profile.release]
rustflags = [ "-C", "..." ]

要在 Cargo 配置中的配置文件中设置它，您需要使用 -Z profile-rustflags 或 [unstable] 表来启用它。例如，

# .cargo/config.toml
[unstable]
profile-rustflags = true

[profile.release]
rustflags = [ "-C", "..." ]

rustdoc-map

跟踪问题：#8296

此功能添加了传递给 rustdoc 的配置设置，以便它可以在未记录依赖项时生成指向文档托管在其他地方的依赖项的链接。首先，将此添加到 .cargo/config

[doc.extern-map.registries]
crates-io = "https://docs.rs/"

然后，在构建文档时，使用以下标志使指向依赖项的链接链接到 docs.rs

cargo +nightly doc --no-deps -Zrustdoc-map

registries 表包含注册表名称到要链接到的 URL 的映射。URL 可能具有标记 {pkg_name} 和 {version}，它们将被替换为相应的值。如果两者均未指定，则 Cargo 默认将 {pkg_name}/{version}/ 附加到 URL 的末尾。

另一个配置设置可用于重定向标准库链接。默认情况下，rustdoc 创建指向 https://doc.rust-lang.net.cn/nightly/ 的链接。要更改此行为，请使用 doc.extern-map.std 设置

[doc.extern-map]
std = "local"

值为 "local" 表示链接到 rustc sysroot 中的文档。如果您使用的是 rustup，则可以使用 rustup component add rust-docs 安装此文档。

默认值为 "remote"。

该值也可以采用自定义位置的 URL。

per-package-target

跟踪问题：#9406
原始拉取请求：#9030
原始问题：#7004

per-package-target 功能为清单添加了两个键：package.default-target 和 package.forced-target。第一个使包默认情况下（即，当未传递 --target 参数时）为某个目标编译。第二个使包始终为目标编译。

例子

[package]
forced-target = "wasm32-unknown-unknown"

在这个例子中，crate 总是为 wasm32-unknown-unknown 构建，例如因为它将被用作在主机（或在命令行上提供）目标上运行的主程序的插件。

artifact-dependencies

跟踪问题：#9096
原始拉取请求：#9992

工件依赖项允许 Cargo 包依赖于 bin、cdylib 和 staticlib crate，并在编译时使用这些 crate 构建的工件。

使用 -Z bindeps 运行 cargo 以启用此功能。

工件依赖项：依赖项声明

工件依赖项将以下键添加到 Cargo.toml 中的依赖项声明中

artifact — 这指定要构建的 Cargo 目标。通常，如果没有此字段，Cargo 将仅从依赖项构建 [lib] 目标。此字段允许指定将构建哪个目标，并在构建时将其作为二进制文件提供
- "bin" — 编译后的可执行二进制文件，对应于依赖项清单中的所有 [[bin]] 部分。
- "bin:<bin-name>" — 编译后的可执行二进制文件，对应于由给定 <bin-name> 指定的特定二进制目标。
- "cdylib" — 与 C 兼容的动态库，对应于依赖项清单中 crate-type = ["cdylib"] 的 [lib] 部分。
- "staticlib" — 与 C 兼容的静态库，对应于依赖项清单中 crate-type = ["staticlib"] 的 [lib] 部分。
artifact 值可以是字符串，也可以是字符串数组以指定多个目标。

例子
```
[dependencies]
bar = { version = "1.0", artifact = "staticlib" }
zoo = { version = "1.0", artifact = ["bin:cat", "bin:dog"]}
```
lib — 这是一个布尔值，指示是否还要将依赖项的库构建为普通的 Rust lib 依赖项。仅当指定了 artifact 时，才能指定此字段。

指定 artifact 时，此字段的默认值为 false。如果将其设置为 true，则还将为声明包正在构建的目标平台构建依赖项的 [lib] 目标。这允许包除了工件依赖项之外，还可以像普通依赖项一样从 Rust 代码中使用依赖项。

例子
```
[dependencies]
bar = { version = "1.0", artifact = "bin", lib = true }
```
target — 要为其构建依赖项的目标平台。仅当指定了 artifact 时，才能指定此字段。

如果未指定，则默认值取决于依赖项类型。对于构建依赖项，它将为主机目标构建。对于所有其他依赖项，它将为声明包构建的相同目标构建。

对于构建依赖项，这也可以采用特殊值 "target"，这意味着为包正在构建的相同目标构建依赖项。
```
[build-dependencies]
bar = { version = "1.0", artifact = "cdylib", target = "wasm32-unknown-unknown"}
same-target = { version = "1.0", artifact = "bin", target = "target" }
```

工件依赖项：环境变量

构建工件依赖项后，Cargo 提供以下环境变量，您可以使用它们来访问工件

CARGO_<ARTIFACT-TYPE>_DIR_<DEP> — 这是包含依赖项中所有工件的目录。

<ARTIFACT-TYPE> 是为依赖项指定的 artifact（大写，如 CDYLIB、STATICLIB 或 BIN），<DEP> 是依赖项的名称。与其他 Cargo 环境变量一样，依赖项名称将转换为大写，破折号替换为下划线。

如果您的清单重命名了依赖项，则 <DEP> 对应于您指定的名称，而不是原始包名称。
CARGO_<ARTIFACT-TYPE>_FILE_<DEP>_<NAME> — 这是工件的完整路径。

<ARTIFACT-TYPE> 是为依赖项指定的 artifact（如上所述大写），<DEP> 是依赖项的名称（如上所述转换），<NAME> 是依赖项中工件的名称。

请注意，<NAME> 不会以任何方式从提供工件的 crate 中指定的 name 或未指定时的 crate 名称进行修改；例如，它可以是小写的，或者包含破折号。

为方便起见，如果工件名称与原始包名称匹配，Cargo 还会提供此变量的副本，并省略 _<NAME> 后缀。例如，如果 cmake crate 提供了一个名为 cmake 的二进制文件，Cargo 会同时提供 CARGO_BIN_FILE_CMAKE 和 CARGO_BIN_FILE_CMAKE_cmake。

对于每种依赖项，这些变量都提供给构建过程中可以访问该种依赖项的部分

对于构建依赖项，这些变量提供给 build.rs 脚本，并且可以使用 std::env::var_os 访问。（与任何操作系统文件路径一样，这些路径可能是也可能不是有效的 UTF-8。）
对于普通依赖项，这些变量在 crate 编译期间提供，并且可以使用 env! 宏访问。
对于开发依赖项，这些变量在示例、测试和基准测试的编译期间提供，并且可以使用 env! 宏访问。

工件依赖项：示例

示例：使用构建脚本中的二进制可执行文件

在 Cargo.toml 文件中，您可以指定对二进制文件的依赖项，以便为构建脚本提供该二进制文件

[build-dependencies]
some-build-tool = { version = "1.0", artifact = "bin" }

然后在构建脚本中，可以在构建时执行二进制文件

fn main() {
    let build_tool = std::env::var_os("CARGO_BIN_FILE_SOME_BUILD_TOOL").unwrap();
    let status = std::process::Command::new(build_tool)
        .arg("do-stuff")
        .status()
        .unwrap();
    if !status.success() {
        eprintln!("failed!");
        std::process::exit(1);
    }
}

示例：在构建脚本中使用 cdylib 工件

使用包中的 Cargo.toml，为特定构建目标将 bar 库构建为 cdylib…

[build-dependencies]
bar = { artifact = "cdylib", version = "1.0", target = "wasm32-unknown-unknown" }

…以及 build.rs 中的构建脚本。

fn main() {
    wasm::run_file(std::env::var("CARGO_CDYLIB_FILE_BAR").unwrap());
}

示例：在二进制文件中使用二进制工件及其库

使用包中的 Cargo.toml，构建 bar 二进制文件以作为工件包含，同时将其作为库提供…

[dependencies]
bar = { artifact = "bin", version = "1.0", lib = true }

…以及使用 main.rs 的可执行文件。

fn main() {
    bar::init();
    command::run(env!("CARGO_BIN_FILE_BAR"));
}

发布超时

跟踪问题：11222

配置文件中的 publish.timeout 键可用于控制 cargo publish 在将包发布到注册表和它在本地索引中可用之间等待的时间。

超时 0 会阻止执行任何检查。当前默认值为 60 秒。

它需要设置 -Zpublish-timeout 命令行选项。

# config.toml
[publish]
timeout = 300  # in seconds

非对称令牌

跟踪问题：10519
RFC：#3231

-Z asymmetric-token 标志启用 cargo:paseto 凭据提供程序，该程序允许 Cargo 向注册表进行身份验证，而无需通过网络发送密钥。

在 config.toml 和 credentials.toml 文件中，有一个名为 private-key 的字段，它是一个以 PASERK 的密钥子集格式化的私钥，用于对非对称令牌进行签名

可以使用 cargo login --generate-keypair 生成密钥对，这将

以当前推荐的方式生成公钥/私钥对。
将私钥保存在 credentials.toml 中。
以 PASERK 公钥格式打印公钥。

建议将 private-key 保存在 credentials.toml 中。它在 config.toml 中也受支持，主要是为了可以使用关联的环境变量进行设置，这是在 CI 上下文中提供它的推荐方法。此设置与我们用于设置密钥令牌的 token 字段相同。

还有一个名为 private-key-subject 的可选字段，它是由注册表选择的字符串。此字符串将作为非对称令牌的一部分包含在内，并且不应该是密钥。它适用于“加密证明中央 CA 服务器授权此操作”等罕见用例。Cargo 要求它是非空白可打印 ASCII 字符。需要非 ASCII 数据的注册表应对其进行 base64 编码。

可以使用 cargo login --registry=name --private-key --private-key-subject="subject" 设置这两个字段，这将提示您输入密钥值。

注册表最多可以设置 private-key 或 token 中的一个。

所有 PASETO 都将包含 iat，即以 ISO 8601 格式表示的当前时间。Cargo 将在适当时包含以下内容

sub 一个可选的、非密钥字符串，由注册表选择，预计每次请求都会声明。该值将是 config.toml 文件中的 private-key-subject。
mutation 如果存在，则表示此请求是一个 mutating 操作（如果不存在，则是一个只读操作），必须是字符串 publish、yank 或 unyank 之一。
- name 与此请求相关的 crate 的名称。
- vers 与此请求相关的 crate 的版本字符串。
- cksum crate 内容的 SHA256 哈希值，以 64 个小写十六进制数字的字符串表示，仅当 mutation 等于 publish 时才必须存在
challenge 此会话中从此服务器收到的 401/403 的质询字符串。发出质询的注册表必须跟踪已发出/使用的质询，并且在同一有效期内永远不要接受给定的质询超过一次（避免需要跟踪曾经发出的每个质询）。

“页脚”（签名的一部分）将是一个 UTF-8 编码的 JSON 字符串，并包含

url Cargo 获取 config.json 文件的 RFC 3986 兼容 URL，
- 如果这是一个带有 HTTP 索引的注册表，则这是所有索引查询都相对于的基 URL。
- 如果这是一个带有 GIT 索引的注册表，则它是 Cargo 用于克隆索引的 URL。
kid 用于对请求进行签名的私钥的标识符，使用 PASERK ID 标准。

PASETO 包含已签名的消息，因此服务器不必从请求中重建确切的字符串来检查签名。服务器确实需要检查签名对于 PASETO 中的字符串是否有效，以及该字符串的内容是否与请求匹配。如果请求应该包含声明但 PASETO 中缺少声明，则必须拒绝该请求。

`cargo config`

原始问题：#2362
跟踪问题：#9301

cargo config 子命令提供了一种显示 cargo 加载的配置文件的方法。它目前包含 get 子命令，该子命令可以采用可选的配置值来显示。

cargo +nightly -Zunstable-options config get build.rustflags

如果未包含配置值，它将显示所有配置值。有关可用选项的更多信息，请参阅 --help 输出。

rustc `--print`

跟踪问题：#9357

cargo rustc --print=VAL 将 --print 标志转发给 rustc，以便从 rustc 中提取信息。这将使用相应的 --print 标志运行 rustc，然后立即退出，而不进行编译。将其作为 cargo 标志公开允许 cargo 根据当前配置注入正确的目标和 RUSTFLAGS。

主要用例是运行 cargo rustc --print=cfg 以获取适用于目标并受任何其他 RUSTFLAGS 影响的配置值。

不同的二进制文件名

跟踪问题：#9778
PR：#9627

different-binary-name 功能允许设置二进制文件的名称，而不必遵守对 crate 名称的限制。例如，crate 名称只能使用 字母数字 字符或 - 或 _，并且不能为空。

filename 参数不应包含二进制文件扩展名，cargo 会自行确定适当的扩展名并将其用于二进制文件。

filename 参数仅在清单的 [[bin]] 部分可用。

cargo-features = ["different-binary-name"]

[package]
name =  "foo"
version = "0.0.1"

[[bin]]
name = "foo"
filename = "007bar"
path = "src/main.rs"

抓取示例

RFC：#3123
跟踪问题：#9910

-Z rustdoc-scrape-examples 标志告诉 Rustdoc 在当前工作区中搜索对函数的调用。然后将这些调用站点包含为文档。您可以像这样使用该标志

cargo doc -Z unstable-options -Z rustdoc-scrape-examples

默认情况下，Cargo 将从要记录的包的示例目标中抓取示例。您可以使用 doc-scrape-examples 标志单独启用或禁用要抓取的目标，例如

# Enable scraping examples from a library
[lib]
doc-scrape-examples = true

# Disable scraping examples from an example target
[[example]]
name = "my-example"
doc-scrape-examples = false

关于测试的注意事项：在测试目标上启用 doc-scrape-examples 目前不会产生任何影响。从测试中抓取示例是一项正在进行的工作。

关于开发依赖项的注意事项：记录库通常不需要 crate 的开发依赖项。但是，示例目标需要开发依赖项。为了向后兼容，-Z rustdoc-scrape-examples 不会为 cargo doc 引入开发依赖项要求。因此，在以下情况下，不会从示例目标中抓取示例

没有要记录的目标需要开发依赖项，并且
至少有一个具有要记录目标的 crate 具有开发依赖项，并且
所有 [[example]] 目标的 doc-scrape-examples 参数都未设置或为 false。

如果您希望从示例目标中抓取示例，则不得满足上述任何一个条件。例如，您可以为一个示例目标将 doc-scrape-examples 设置为 true，这向 Cargo 发出信号，表明您可以接受为 cargo doc 构建开发依赖项。

rustdoc 的输出格式

跟踪问题：#13283

此标志确定 cargo rustdoc 的输出格式，接受 html 或 json，为工具提供了一种依赖 rustdoc 的实验性 JSON 格式的方法。

您可以像这样使用该标志

cargo rustdoc -Z unstable-options --output-format json

检查配置

RFC：#3013
跟踪问题：#10554

-Z check-cfg 命令行参数使用 rustc 和 rustdoc 不稳定的 --check-cfg 命令行参数，在 #[cfg]、cfg!、#[link] 和 #[cfg_attr] 中启用 Cargo 功能以及 rustc 已知名称和值的编译时检查。

您可以像这样使用该标志

cargo check -Z unstable-options -Z check-cfg

`cargo::rustc-check-cfg=CHECK_CFG`

rustc-check-cfg 指令告诉 Cargo 将给定值传递给编译器的 --check-cfg 标志。这可用于在编译时检测意外的条件编译名称和/或值。

这只能与 -Zcheck-cfg 结合使用，否则将被忽略并发出警告。

如果您想与 Cargo 功能集成，请仅使用 -Zcheck-cfg，而不要尝试使用此选项手动执行。

您可以像这样使用该指令

#![allow(unused)]
fn main() {
// build.rs
println!("cargo::rustc-check-cfg=cfg(foo, bar)");
}

cargo check -Z unstable-options -Z check-cfg

代码生成后端

codegen-backend 功能可以使用配置文件选择 rustc 使用的代码生成后端。

例子

[package]
name = "foo"

[dependencies]
serde = "1.0.117"

[profile.dev.package.foo]
codegen-backend = "cranelift"

要在 Cargo 配置中的配置文件中设置此项，您需要使用 -Z codegen-backend 或 [unstable] 表将其启用。例如，

# .cargo/config.toml
[unstable]
codegen-backend = true

[profile.dev.package.foo]
codegen-backend = "cranelift"

gitoxide

跟踪问题：#11813

使用“gitoxide”不稳定功能，所有或指定的 git 操作将由 gitoxide crate 而不是 git2 执行。

虽然 -Zgitoxide 启用了当前实现的所有功能，但可以使用 -Zgitoxide=operation[,operationN] 语法单独选择要使用 gitoxide 运行的 git 操作。

有效操作如下

fetch - 所有获取都使用 gitoxide 完成，包括 git 依赖项以及 crates 索引。
checkout （计划中） - 检出工作树，支持过滤器和子模块。

git

跟踪问题：#13285

使用“git”不稳定功能，gitoxide 和 git2 都将对 crate 索引和 git 依赖项执行浅层获取。

虽然 -Zgit 启用了当前实现的所有功能，但可以使用 -Zgit=operation[,operationN] 语法单独选择何时执行浅层获取。

有效操作如下

shallow-index - 对索引执行浅层克隆。
shallow-deps - 对 git 依赖项执行浅层克隆。

关于浅层克隆的详细信息

要启用浅层克隆，请添加 -Zgit=shallow-deps 以获取 git 依赖项，或添加 -Zgit=shallow-index 以获取注册表索引。
浅层克隆和浅层检出的 git 存储库位于其自己的 -shallow 后缀目录中，即
- ~/.cargo/registry/index/*-shallow
- ~/.cargo/git/db/*-shallow
- ~/.cargo/git/checkouts/*-shallow
启用不稳定功能后，获取/克隆 git 存储库始终是浅层获取。这大致相当于在任何地方都使用 git fetch --depth 1。
即使存在 Cargo.lock 或指定了提交 { rev = "…" }，gitoxide 和 libgit2 也足够智能，可以在不取消现有存储库的浅层化的情况下执行浅层获取。

脚本

跟踪问题：#12207

Cargo 可以直接运行 .rs 文件，如

$ cargo +nightly -Zscript file.rs

其中 file.rs 可以像这样简单

fn main() {}

用户可以选择在模块级注释中的 cargo 代码围栏中指定清单，例如

#!/usr/bin/env -S cargo +nightly -Zscript
```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);
}

单文件包

除了现有的多文件包（包含其他 .rs 文件的 Cargo.toml 文件）之外，我们还添加了单文件包的概念，这些包可能包含嵌入式清单。单文件 .rs 包与任何其他 .rs 文件之间没有必要的区别。

可以使用 --manifest-path 选择单文件包，例如 cargo test --manifest-path foo.rs。与 Cargo.toml 不同，无法自动发现这些文件。

单文件包可能包含嵌入式清单。嵌入式清单使用 TOML 存储在 rust“frontmatter”中，这是一个 markdown 代码围栏，在文件顶部的信息字符串开头带有 cargo。

推断/默认的清单字段

package.name = <文件名的 slug 化版本>
package.edition = <当前版本> 以避免始终必须添加嵌入式清单，但代价是可能会破坏 rust 升级后的脚本
- 未指定 edition 时发出警告，以提高对此的认识

不允许使用的清单字段

[workspace]、[lib]、[[bin]]、[[example]]、[[test]]、[[bench]]
package.workspace、package.build、package.links、package.autobins、package.autoexamples、package.autotests、package.autobenches

单文件包的默认 CARGO_TARGET_DIR 位于 $CARGO_HOME/target/<哈希值>

单文件包的锁定文件将放置在 CARGO_TARGET_DIR 中。将来，当支持工作区时，这将允许用户拥有持久化的锁定文件。

清单命令

您可以将清单直接传递给 cargo 命令，而无需子命令，例如 foo/Cargo.toml 或单文件包，例如 foo.rs。这主要用于放在 #! 行中。

解释 cargo <子命令> 的优先级如下

内置包或单文件包
别名
外部子命令

如果参数具有以下任何一项，则将其标识为清单命令：

路径分隔符
.rs 扩展名
文件名是 Cargo.toml

cargo run --manifest-path <path> 和 cargo <path> 之间的区别

cargo <path> 使用 <path> 的配置运行，而不是当前目录的配置，更像是 cargo install --path <path>
cargo <path> 的详细程度低于正常的默认值。传递 -v 以获取正常输出。

文档更新

2024 版

跟踪问题： (尚未创建)
RFC: rust-lang/rfcs#3501

可以通过将 edition2024 不稳定功能添加到 Cargo.toml 的顶部来启用对 2024 版的支持

cargo-features = ["edition2024"]

[package]
name = "my-package"
version = "0.1.0"
edition = "2024"

如果要将现有项目从以前的版本转换，则可以在 nightly 频道上使用 cargo fix --edition。运行 cargo fix 后，您可以按照上面的说明将版本切换到 2024。

此功能非常不稳定，仅用于早期测试和实验。未来的 nightly 版本可能会引入 2024 版的更改，这些更改可能会破坏您的构建。

配置文件 `trim-paths` 选项

跟踪问题： rust-lang/cargo#12137
跟踪 Rustc 问题： rust-lang/rust#111540

这添加了一个新的配置文件设置，用于控制如何在生成的二进制文件中清理路径。可以像这样启用

cargo-features = ["trim-paths"]

[package]
# ...

[profile.release]
trim-paths = ["diagnostics", "object"]

要在 Cargo 配置中的配置文件中设置此项，您需要使用 -Z trim-paths 或 [unstable] 表来启用它。例如，

# .cargo/config.toml
[unstable]
trim-paths = true

[profile.release]
trim-paths = ["diagnostics", "object"]

文档更新

trim-paths

作为新的 “配置文件设置”条目

trim-paths 是一个配置文件设置，用于启用和控制构建输出中文件路径的清理。它采用以下值

"none" 和 false — 禁用路径清理
"macro" — 在 std::file!() 宏的扩展中清理路径。这是嵌入式恐慌消息中路径的来源
"diagnostics" — 清理打印的编译器诊断信息中的路径
"object" — 清理已编译的可执行文件或库中的路径
"all" 和 true — 清理所有可能位置的路径

它还接受包含 "macro"、"diagnostics" 和 "object" 组合的数组。

对于 dev 配置文件，它默认为 none，对于 release 配置文件，它默认为 object。您可以通过在 Cargo.toml 中指定此选项来手动覆盖它

[profile.dev]
trim-paths = "all"

[profile.release]
trim-paths = ["object", "diagnostics"]

默认的 release 配置文件设置 (object) 仅清理已发出的可执行文件或库文件中的路径。它始终会影响来自宏（如恐慌消息）的路径，并且仅在调试信息将与二进制文件一起嵌入时才会影响调试信息（在具有 ELF 二进制文件的平台上默认，例如 Linux 和 windows-gnu），但如果它们位于单独的文件中，则不会触及它们（Windows MSVC 和 macOS 上的默认设置）。但指向这些单独文件的路径会被清理。

如果 trim-paths 不是 none 或 false，则如果以下路径出现在选定的范围内，则会对其进行清理

标准库和核心库（sysroot）的源文件路径将以 /rustc/[rustc commit hash] 开头，例如 /home/username/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/result.rs -> /rustc/fe72845f7bb6a77b9e671e6a4f32fe714962cec4/library/core/src/result.rs
当前包的路径将被剥离，相对于当前工作空间根目录，例如 /home/username/crate/src/lib.rs -> src/lib.rs。
依赖包的路径将替换为 [package name]-[version]。例如 /home/username/deps/foo/src/lib.rs -> foo-0.1.0/src/lib.rs

当标准库和核心库的源文件路径不在清理范围内时，发出的路径将取决于 rust-src 组件是否存在。如果存在，则某些路径将指向文件系统上源文件的副本；如果不存在，则它们将显示为 /rustc/[rustc commit hash]/library/...（就像选择对其进行清理时一样）。指向所有其他源文件的路径将不受影响。

这不会影响源代码中任何硬编码的路径，例如字符串中的路径。

环境变量

作为 “Cargo 为构建脚本设置的环境变量” 的新条目

CARGO_TRIM_PATHS — trim-paths 配置文件选项的值。false、"none" 和空数组将转换为 none。true 和 "all" 变为 all。非空数组中的值将连接成逗号分隔的列表。如果构建脚本引入了构建工件的绝对路径（例如通过调用编译器），则用户可以请求在不同类型的工件中对其进行清理。需要清理的常见路径包括 OUT_DIR 和 CARGO_MANIFEST_DIR，以及构建脚本引入的任何其他路径，例如包含目录。

gc

跟踪问题： #12633

-Zgc 标志启用 cargo 主目录中 cargo 全局缓存内的垃圾收集。这包括下载的依赖项，例如压缩的 .crate 文件、解压缩的 src 目录、注册表索引缓存和 git 依赖项。当存在 -Zgc 时，cargo 将跟踪任何索引和依赖项的最后一次使用时间，然后使用这些时间戳手动或自动删除一段时间未使用的缓存条目。

cargo build -Zgc

自动垃圾收集

自动删除发生在已经在执行大量工作的命令上，例如所有构建命令（cargo build、cargo test、cargo check 等）和 cargo fetch。删除发生在解析之后和包下载之后。自动删除每天只执行一次（有关配置，请参阅 gc.auto.frequency）。如果 cargo 处于离线状态（例如使用 --offline 或 --frozen），则会禁用自动删除，以避免删除如果您长时间离线可能需要使用的工件。

自动 gc 配置

可以通过 cargo 配置设置来指定自动 gc 行为。可用的设置有

# Example config.toml file.

# This table defines the behavior for automatic garbage collection.
[gc.auto]
# The maximum frequency that automatic garbage collection happens.
# Can be "never" to disable automatic-gc, or "always" to run on every command.
frequency = "1 day"
# Anything older than this duration will be deleted in the source cache.
max-src-age = "1 month"
# Anything older than this duration will be deleted in the compressed crate cache.
max-crate-age = "3 months"
# Any index older than this duration will be deleted from the index cache.
max-index-age = "3 months"
# Any git checkout older than this duration will be deleted from the checkout cache.
max-git-co-age = "1 month"
# Any git clone older than this duration will be deleted from the git cache.
max-git-db-age = "3 months"

使用 `cargo clean` 进行手动垃圾收集

可以使用 cargo clean gc 命令执行手动删除。可以通过传递以下缓存选项之一来执行缓存内容的删除

--max-src-age=DURATION — 删除自给定时间以来未使用的源缓存文件。
--max-crate-age=DURATION — 删除自给定时间以来未使用的 crate 缓存文件。
--max-index-age=DURATION — 删除自给定时间以来未使用的注册表索引（包括其 .crate 和 src 文件）。
--max-git-co-age=DURATION — 删除自给定时间以来未使用的 git 依赖项签出。
--max-git-db-age=DURATION — 删除自给定时间以来未使用的 git 依赖项克隆。
--max-download-age=DURATION — 删除自给定时间以来未使用的任何下载的缓存数据。
--max-src-size=SIZE — 删除最旧的源缓存文件，直到缓存低于给定大小。
--max-crate-size=SIZE — 删除最旧的 crate 缓存文件，直到缓存低于给定大小。
--max-git-size=SIZE — 删除最旧的 git 依赖项缓存，直到缓存低于给定大小。
--max-download-size=SIZE — 删除最旧的下载缓存数据，直到缓存低于给定大小。

DURATION 的指定格式为“N 秒/分钟/小时/天/周/月”，其中 N 是一个整数。

SIZE 的指定格式为“N suffix”，其中 suffix 是 B、kB、MB、GB、kiB、MiB 或 GiB，N 是一个整数或浮点数。如果没有指定后缀，则该数字为字节数。

cargo clean gc
cargo clean gc --max-download-age=1week
cargo clean gc --max-git-size=0 --max-download-size=100MB

open-namespaces

跟踪问题： #13576

允许多个包参与同一个 API 命名空间

可以像这样启用

cargo-features = ["open-namespaces"]

[package]
# ...

Cargo 手册