不稳定的功能

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

经过一段时间后，如果该功能没有任何重大问题，则可以将其 stabilized（稳定化），一旦当前的 nightly 版本到达 stable channel（大约 6 到 12 周），它将在 stable channel 上可用。

不稳定的功能可以通过三种不同的方式启用，具体取决于功能的工作方式

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 选项。例如，新的 --artifact-dir 选项仅在 nightly 版本上可用

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

cargo +nightly build -Z mtime-on-use

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

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

下面描述的每个新功能都应解释如何使用它。

对于最新的 nightly 版本，请参阅此页面的 nightly version。

不稳定功能列表

特定于不稳定的功能
- -Z allow-features — 提供了一种限制使用哪些不稳定功能的方法。
构建脚本和链接
- Metabuild — 提供声明式构建脚本。
Resolver 和功能
- no-index-update — 阻止 cargo 更新索引缓存。
- avoid-dev-deps — 阻止 resolver 在解析期间包含 dev-dependencies。
- minimal-versions — 强制 resolver 使用最低兼容版本而不是最高版本。
- direct-minimal-versions — 强制 resolver 使用最低兼容版本而不是最高版本。
- public-dependency — 允许将依赖项分类为 public 或 private。
- msrv-policy — MSRV 感知 resolver 和版本选择
- precise-pre-release — 允许使用 update --precise 选择预发布版本
- update-breaking — 允许使用 update --breaking 升级到破坏性版本
输出行为
- artifact-dir — 添加一个目录，用于复制 artifacts。
- 不同的二进制名称 — 为构建的二进制文件分配一个与 crate 名称不同的名称。
- root-dir — 控制打印路径时所依据的根目录
编译行为
- mtime-on-use — 每次使用时更新每个依赖项的最后修改时间戳，以提供一种删除未使用 artifacts 的机制。
- doctest-xcompile — 支持使用 --target 标志运行 doctests。
- build-std — 构建标准库而不是使用预构建的二进制文件。
- build-std-features — 设置与标准库一起使用的功能。
- binary-dep-depinfo — 使 dep-info 文件跟踪二进制依赖项。
- checksum-freshness — 传递后，将使用文件 checksums 而不是文件 mtime 来决定是否需要重建 crate。
- panic-abort-tests — 允许使用 “abort” panic strategy 运行测试。
- host-config — 允许为主机构建目标设置类似 [target] 的配置设置。
- target-applies-to-host — 更改某些标志是否会传递给主机构建目标。
- gc — 全局缓存垃圾回收。
- open-namespaces — 允许多个包参与相同的 API 命名空间
rustdoc
- rustdoc-map — 提供文档映射以链接到外部站点，如 docs.rs。
- scrape-examples — 在文档中显示示例。
- output-format — 允许以实验性的 JSON format 发射文档。
Cargo.toml 扩展
- Profile rustflags option — 直接传递给 rustc。
- codegen-backend — 选择 rustc 使用的 codegen backend。
- per-package-target — 设置每个单独的包要使用的 --target。
- artifact dependencies — 允许将构建 artifacts 包含到其他构建 artifacts 中，并为不同的 targets 构建它们。
- Profile trim-paths option — 控制构建输出中文件路径的清理。
- [lints.cargo] — 允许为 Cargo 配置 lints。
- path bases — 路径依赖项的命名基本目录。
信息和元数据
- Build-plan — 发射关于将要运行哪些命令的 JSON 信息。
- unit-graph — 为 Cargo 的内部图结构发射 JSON。
- cargo rustc --print — 使用 --print 调用 rustc 以显示来自 rustc 的信息。
配置
- config-include — 添加配置文件包含其他文件的能力。
- cargo config — 添加一个新的子命令用于查看配置文件。
注册表
- publish-timeout — 控制上传 crate 和在索引中可用之间的时间间隔
- asymmetric-token — 添加对使用非对称加密（cargo:paseto provider）的身份验证令牌的支持。
其他
- gitoxide — 使用 gitoxide 而不是 git2 进行一组操作。
- script — 启用对单文件 .rs 包的支持。
- lockfile-path — 允许指定 lockfile 的路径，而不是默认路径 <workspace_root>/Cargo.lock。
- package-workspace — 允许在 workspace 中打包和发布多个 crates。
- native-completions — 将 cargo shell completions 移动到 native completions。
- warnings — 控制 warning 行为；允许或拒绝 warnings 的选项。

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

原始 Issue：#3479
追踪 Issue：#7404

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

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

avoid-dev-deps

原始 Issue：#4988
追踪 Issue：#5133

当运行诸如 cargo install 或 cargo build 之类的命令时，Cargo 目前要求下载 dev-dependencies，即使它们未使用。 -Z avoid-dev-deps 标志允许 Cargo 在不需要 dev-dependencies 时避免下载它们。如果跳过 dev-dependencies，则不会生成 Cargo.lock 文件。

minimal-versions

原始 Issue：#4100
追踪 Issue：#5657

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

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

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

direct-minimal-versions

原始 Issue：#4100
追踪 Issue：#5657

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

间接依赖项像往常一样解析，以免受到其最小版本验证的阻止。

artifact-dir

原始 Issue：#4875
追踪 Issue：#6790

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


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

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


[build]
artifact-dir = "out"

root-dir

原始 Issue：#9887
追踪 Issue：None（目前未计划稳定化）

-Zroot-dir 标志设置打印路径时所依据的根目录。这会影响诊断和 file!() 宏发出的路径。

doctest-xcompile

追踪 Issue：#7040
追踪 Rustc Issue：#64245

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


cargo test --target foo -Zdoctest-xcompile

Build-plan

追踪 Issue：#5579

build-plan 功能已弃用，可能会在未来版本中删除。请参阅 https://github.com/rust-lang/cargo/issues/7614。

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


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

Metabuild

追踪 Issue：rust-lang/rust#49803
RFC：#2196

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

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


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 包应具有一个名为 metabuild 的公共函数，该函数执行与常规 build.rs 脚本相同的操作。

public-dependency

追踪 Issue：#44663

“public-dependency” 功能允许将依赖项标记为 “public” 或 “private”。启用此功能后，将向 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 的 “The dependencies table” 部分，将 public 作为 workspace.dependencies 的不受支持字段包含在内

msrv-policy

RFC：MSRV 感知 Resolver
#9930 (MSRV 感知 resolver)

RFC RFC 2495 下 MSRV 感知 cargo 功能的 catch-all 不稳定功能。

MSRV 感知 cargo add

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

MSRV 感知 resolver

这已在 1.84 版本中 #14639 稳定化。

将 `incompatible_toolchain` 错误转换为 lint

未实现

`cargo add`、`cargo update` 的 `--update-rust-version` 标志

未实现

`package.rust-version = "toolchain"`

未实现

更新 `cargo new` 模板以设置 `package.rust-version = "toolchain"`

未实现

precise-pre-release

追踪 Issue：#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。

update-breaking

追踪 Issue：#12425

允许使用 --breaking 标志在 SemVer 不兼容的版本之间升级 Cargo.toml 中的依赖项版本要求。

这仅适用于以下情况的依赖项：

包是 workspace 成员的依赖项
依赖项未重命名
有 SemVer 不兼容的版本可用
使用 “SemVer operator”（^，这是默认值）

用户可以进一步限制通过在命令行上指定要升级的包。

示例


$ cargo +nightly -Zunstable-options update --breaking
$ cargo +nightly -Zunstable-options update --breaking clap

这旨在发挥与 cargo-upgrade 类似的作用

build-std

追踪仓库：https://github.com/rust-lang/wg-cargo-std-aware

build-std 功能使 Cargo 能够将标准库本身编译为 crate 图编译的一部分。此功能在历史上也被称为 “std-aware Cargo”。此功能仍处于开发的早期阶段，并且也可能是 Cargo 的一项巨大的功能添加。即使以今天存在的最小形式进行记录，这也是一个非常大的功能，因此，如果您想及时了解最新信息，您需要关注追踪仓库及其 issue 集。

今天实现的功能位于名为 -Z build-std 的标志之后。此标志指示 Cargo 应使用与主构建本身相同的 profile 从源代码编译标准库。请注意，为了使此功能正常工作，您需要具有标准库的源代码，并且目前唯一支持的方法是添加 rust-src rust rustup 组件


$ rustup component add rust-src --toolchain nightly

用法如下所示


$ 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!

在这里，我们在 debug 模式下使用 debug assertions 重新编译了标准库（就像编译 src/main.rs 一样），并且所有内容都在最后链接在一起。

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


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

此处的 value 是要构建的标准库 crates 的逗号分隔列表。

要求

作为总结，今天使用 -Z build-std 的要求列表是

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

报告 bugs 和提供帮助

-Z build-std 功能处于开发的早期阶段！Cargo 的此功能具有极其悠久的历史，并且范围非常大，而这仅仅是开始。如果您想报告 bugs，请将其报告给

Cargo — https://github.com/rust-lang/cargo/issues/new — 用于 implementation bugs
追踪仓库 — https://github.com/rust-lang/wg-cargo-std-aware/issues/new — 用于更大的 design questions。

此外，如果您想看到尚未实现的功能和/或某些功能无法完全按照您希望的方式工作，请随时查看追踪仓库的 issue tracker，如果它不在那里，请提交一个新的 issue！

build-std-features

追踪仓库：https://github.com/rust-lang/wg-cargo-std-aware

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

binary-dep-depinfo

追踪 rustc issue：#63012

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

checksum-freshness

追踪 issue：#14136

-Z checksum-freshness 标志将用文件 checksum value 替换 cargo 的指纹中的文件 mtime 的使用。这在 mtime implementation 较差的系统或 CI/CD 中最有用。checksum 算法可能会在 cargo 版本之间更改，恕不另行通知。指纹由 cargo 用于确定何时需要重建 crate。

暂时，即使启用了 checksum-freshness，构建脚本摄取的文件仍将继续使用 mtime。这并非旨在作为长期解决方案。

panic-abort-tests

追踪 Issue：#67650
原始 Pull Request：#7460

-Z panic-abort-tests 标志将启用 nightly 支持，以使用 -Cpanic=abort 编译 test harness crates。如果没有此标志，Cargo 将使用 -Cpanic=unwind 编译测试及其依赖项，因为这是 test-the-crate 知道如何运行的唯一方法。但是，从 rust-lang/rust#64158 开始，test crate 支持带有 test-per-process 的 -C panic=abort，并且可以帮助避免多次编译 crate graphs。

目前尚不清楚此功能将如何在 Cargo 中稳定化，但我们希望以某种方式对其进行稳定化！

config-include

追踪 Issue：#7723

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

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


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

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

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

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

target-applies-to-host

原始 Pull Request：#9322
追踪 Issue：#9453

从历史上看，Cargo 对于是否尊重环境变量和 [target] 中的 linker 和 rustflags 配置选项用于 build scripts、插件以及始终为主机平台构建的其他 artifacts 的行为一直有些不一致。当未传递 --target 时，Cargo 对 build scripts 和所有其他编译 artifacts 采用相同的 linker 和 rustflags。但是，当传递 --target 时，Cargo 从 [target.<host triple>] 尊重 linker，并且不会拾取任何 rustflags 配置。这种双重行为令人困惑，但也使得难以正确配置主机 triple 和 target triple 恰好相同，但旨在在构建主机上运行的 artifacts 仍应进行不同配置的构建。

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

原始 Pull Request：#9322
追踪 Issue：#9452

config 文件中的 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

追踪 Issue：#8002

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


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

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

以下是对 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],
}

Profile `rustflags` option

原始 Issue：rust-lang/cargo#7878
追踪 Issue：rust-lang/cargo#10271

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


cargo-features = ["profile-rustflags"]

[package]
# ...

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

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


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

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

rustdoc-map

追踪 Issue：#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" 的 value 表示链接到在 rustc sysroot 中找到的文档。如果您正在使用 rustup，则可以使用 rustup component add rust-docs 安装此文档。

默认 value 为 "remote"。

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

per-package-target

追踪 Issue：#9406
原始 Pull Request：#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

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

运行带有 -Z bindeps 的 cargo 以启用此功能。

artifact-dependencies: 依赖声明

Artifact-dependencies 在 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" }
```

artifact-dependencies: 环境变量

构建构件依赖项后，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-dependencies，这些变量提供给 build.rs 脚本，可以使用 std::env::var_os 访问。（与任何 OS 文件路径一样，这些可能是也可能不是有效的 UTF-8。）
对于 normal dependencies，这些变量在 crate 的编译期间提供，可以使用 env! 宏访问。
对于 dev-dependencies，这些变量在示例、测试和基准测试的编译期间提供，可以使用 env! 宏访问。

artifact-dependencies: 示例

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

在 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 构件

构建 bar 库作为特定构建目标的 cdylib 的消费包中的 Cargo.toml …


[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());
}

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

构建 bar 二进制文件以包含为构件，同时使其也可用作库的消费包中的 Cargo.toml …


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

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


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

publish-timeout

追踪问题：11222

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

超时时间 0 会阻止任何检查发生。当前的默认值为 60 秒。

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


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

asymmetric-token

追踪问题：10519
RFC: #3231

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

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

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

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

建议将 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 如果存在，则表示此请求是变异操作（如果不存在，则表示只读操作），必须是字符串 publish、yank 或 unyank 之一。
- name 与此请求相关的 crate 的名称。
- vers 与此请求相关的 crate 的版本字符串。
- cksum crate 内容的 SHA256 哈希值，为 64 个小写十六进制数字的字符串，仅当 mutation 等于 publish 时才必须存在
challenge 从此服务器此会话的 401/403 收到的 challenge 字符串。发布 challenge 的注册表必须跟踪已发布/使用的 challenge，并且在同一有效期内永远不要接受给定的 challenge 多次（避免需要跟踪曾经发布的所有 challenge）。

“footer”（签名的一部分）将是 UTF-8 中的 JSON 字符串，并包括

url Cargo 从中获取 config.json 文件的符合 RFC 3986 标准的 URL，
- 如果这是一个具有 HTTP 索引的注册表，则这是所有索引查询都相对于的基础 URL。
- 如果这是一个具有 GIT 索引的注册表，则是 Cargo 用于克隆索引的 URL。
kid 用于签署请求的私钥的标识符，使用 PASERK IDs 标准。

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

`cargo config`

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

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


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

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

rustc `--print`

追踪问题：#9357

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

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

不同的二进制文件名

追踪问题：#9778
PR: #9627

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

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"

scrape-examples

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 目前没有任何效果。从测试中抓取示例是一项正在进行中的工作。

关于 dev-dependencies 的说明： 文档化库通常不需要 crate 的 dev-dependencies。但是，示例目标需要 dev-deps。为了向后兼容，-Z rustdoc-scrape-examples 将不会为 cargo doc 引入 dev-deps 要求。因此，在以下情况下，不会从示例目标中抓取示例

没有要文档化的目标需要 dev-deps，并且
至少一个具有要文档化的目标的 crate 具有 dev-deps，并且
所有 [[example]] 目标的 doc-scrape-examples 参数都未设置或为 false。

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

rustdoc 的 output-format

追踪问题：#13283

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

您可以像这样使用该标志


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

codegen-backend

codegen-backend 功能使您可以选择由 rustc 使用的 codegen 后端，使用 profile。

示例


[package]
name = "foo"

[dependencies]
serde = "1.0.117"

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

要在 Cargo 配置的 profile 中设置此项，您需要使用 -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 - 所有 fetch 操作都使用 gitoxide 完成，其中包括 git 依赖项以及 crates 索引。
checkout (计划中) - 检出工作树，支持过滤器和子模块。

git

追踪问题：#13285

借助 ‘git’ 不稳定功能，gitoxide 和 git2 都将对 crate 索引和 git 依赖项执行浅层 fetch。

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

有效操作如下

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 存储库始终是浅层 fetch。这大致等于所有地方的 git fetch --depth 1。
即使存在 Cargo.lock 或指定提交 { rev = "…" }，gitoxide 和 libgit2 也足够智能，可以进行浅层 fetch 而无需取消浅层化现有存储库。

script

追踪问题：#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 代码围栏，在文件顶部的 infostring 开头带有 cargo。

推断/默认的清单字段

package.name = <slugified file stem>
package.edition = <current> 以避免总是必须添加嵌入式清单，但代价是可能会破坏 rust 升级上的脚本
- 当 edition 未指定时发出警告，以提高对此的认识

不允许的清单字段

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

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

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

Manifest-commands

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

解释 cargo <subcommand> 的优先级是

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

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

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

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

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

文档更新

Profile `trim-paths` 选项

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

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


cargo-features = ["trim-paths"]

[package]
# ...

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

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


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

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

文档更新

trim-paths

作为新的 “Profiles settings” 条目

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

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

它还接受一个数组，其中包含 "macro"、"diagnostics" 和 "object" 的组合。

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


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

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

默认的 release profile 设置 (object) 仅清理发出的可执行文件或库文件中的路径。它始终影响来自宏（例如 panic 消息）的路径，并且仅当调试信息将与二进制文件一起嵌入时（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 profile 选项的值。false、"none" 和空数组将转换为 none。true 和 "all" 变为 all。非空数组中的值将连接成逗号分隔的列表。如果构建脚本引入了对构建构件的绝对路径（例如通过调用编译器），则用户可以请求在不同类型的构件中清理它们。需要清理的常见路径包括 OUT_DIR、CARGO_MANIFEST_DIR 和 CARGO_MANIFEST_PATH，以及构建脚本引入的任何其他路径，例如 include 目录。

gc

追踪问题：#12633

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


cargo build -Zgc

自动垃圾回收

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

自动 gc 配置

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


# 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 seconds/minutes/days/weeks/months” 的形式指定，其中 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]
# ...

`[lints.cargo]`

追踪问题：#12235

一个新的 lints 工具表，用于 cargo，可用于配置 cargo 本身在使用 -Zcargo-lints 时发出的 lint


[lints.cargo]
implicit-features = "warn"

这将与 RFC 2906 workspace-deduplicate 一起使用


[workspace.lints.cargo]
implicit-features = "warn"

[lints]
workspace = true

Path Bases

追踪问题：#14355

path 依赖项可以选择通过将 base 键设置为配置或内置路径基之一中的 [path-bases] 表中的路径基名称来指定基路径。该路径基的值将前置到 path 值（并在必要时加上路径分隔符），以生成 Cargo 将查找依赖项的实际位置。

例如，如果 Cargo.toml 包含


cargo-features = ["path-bases"]

[dependencies]
foo = { base = "dev", path = "foo" }

给定配置中包含 [path-bases] 表，其中包含


[path-bases]
dev = "/home/user/dev/rust/libraries/"

这将生成一个位于 /home/user/dev/rust/libraries/foo 的 path 依赖项 foo。

路径库可以是绝对路径或相对路径。相对路径库是相对于声明该路径库的配置文件的父目录。

路径库的名称只能使用字母数字字符或-或_，必须以字母字符开头，并且不能为空。

如果依赖项中使用的路径库名称既不在配置中，也不是内置路径库之一，那么 Cargo 将引发错误。

内置路径库

Cargo 提供了隐式路径库，无需在 [path-bases] 表中指定它们即可使用。

workspace - 如果项目是工作区或工作区成员，则此路径库被定义为工作区根 Cargo.toml 的父目录。

如果内置路径库名称也在配置中声明，则 Cargo 将优先使用配置中的值。这允许 Cargo 添加新的内置路径库而不会出现兼容性问题（因为现有用法将覆盖内置名称）。

lockfile-path

原始问题: #5707
追踪问题: #14421

此功能允许您指定 lockfile Cargo.lock 的路径。默认情况下，lockfile 写入到 <workspace_root>/Cargo.lock。但是，当源文件存储在只读目录中时，大多数 cargo 命令会因尝试写入 lockfile 而失败。--lockfile-path 标志使处理只读源文件变得更容易。请注意，当前路径必须以 Cargo.lock 结尾。这意味着，如果您想在多个项目中使用此功能，lockfile 应存储在不同的目录中。示例


cargo +nightly metadata --lockfile-path=$LOCKFILES_ROOT/my-project/Cargo.lock -Z unstable-options

package-workspace

追踪问题: #10948

这允许 cargo 打包（或发布）工作区中的多个 crate，即使它们具有相互依赖关系。例如，考虑一个包含包 foo 和 dep 的工作区，其中 foo 依赖于 dep。那么


cargo +nightly -Zpackage-workspace package -p foo -p dep

将同时打包 foo 和 dep，而


cargo +nightly -Zpackage-workspace publish -p foo -p dep

将同时发布 foo 和 dep。如果 foo 和 dep 是工作区中唯一的 crate，则可以使用 --workspace 标志，而不是单独指定 crate


cargo +nightly -Zpackage-workspace package --workspace
cargo +nightly -Zpackage-workspace publish --workspace

Lock-file 行为

当同时打包一个二进制文件及其依赖项之一时，该二进制文件将被打包，并带有一个指向依赖项注册表条目的 lock-file，就好像该依赖项已被发布一样，即使它尚未发布。在这种情况下，cargo 需要知道依赖项最终将发布到的注册表。cargo 将尝试通过检查publish 字段来推断此注册表，如果未设置 publish 字段，则回退到 crates.io。要显式设置注册表，请传递 --registry 或 --index 标志。


cargo +nightly -Zpackage-workspace --registry=my-registry package -p foo -p dep
cargo +nightly -Zpackage-workspace --index=https://example.com package -p foo -p dep

native-completions

原始问题: #6645
追踪问题: #14520

此功能将手写的补全脚本迁移到 Rust 原生，使我们更容易添加、扩展和测试新的补全。此功能通过 nightly channel 启用，无需额外的 -Z 选项。

特别需要反馈的领域

需要转义或引用的参数未被正确处理
信息不准确
命令行解析中的错误
不报告其补全的参数
已知问题造成困扰

反馈可以分解为

报告了哪些补全候选项
- 已知问题: #14520, A-completions
- 报告问题或讨论行为
Shell 集成、命令行解析和补全过滤
- 已知问题: clap#3166, clap 的 A-completions
- 报告问题或讨论行为

如有疑问，您可以在 #14520 或 zulip 中讨论此问题

如何使用 native-completions 功能

bash: 将 source <(CARGO_COMPLETE=bash cargo +nightly) 添加到您的 .bashrc。
zsh: 将 source <(CARGO_COMPLETE=zsh cargo +nightly) 添加到您的 .zshrc。
fish: 将 source (CARGO_COMPLETE=fish cargo +nightly | psub) 添加到 $XDG_CONFIG_HOME/fish/completions/cargo.fish
elvish: 将 eval (E:CARGO_COMPLETE=elvish cargo +nightly | slurp) 添加到 $XDG_CONFIG_HOME/elvish/rc.elv
powershell: 将 CARGO_COMPLETE=powershell cargo +nightly | Invoke-Expression 添加到 $PROFILE。

warnings

原始问题: #8424
追踪问题: #14802

-Z warnings 功能启用 build.warnings 配置选项来控制 Cargo 如何处理警告。如果未启用 -Z warnings 不稳定标志，则 build.warnings 配置将被忽略。

此设置目前仅适用于 rustc 警告。未来可能会应用于其他警告（例如 Cargo lints 或 Cargo 警告）。

`build.warnings`

类型: string
默认值: warn
环境变量: CARGO_BUILD_WARNINGS

控制 Cargo 如何处理警告。允许的值为

warn: 警告作为警告发出（默认）。
allow: 警告被隐藏。
deny: 如果发出警告，则操作结束时将引发错误，并且进程将以失败退出代码退出。

Cargo 书籍