Skip to content

Latest commit

 

History

History
260 lines (165 loc) · 9.08 KB

unstable.md

File metadata and controls

260 lines (165 loc) · 9.08 KB
Raw

Unstable Features

不稳定的特性

实验性 Cargo 特性仅适用于夜间通道(Rust 的 nightly 版本)。您通常使用-Z带其中一个特性，以启用它们。运行cargo -Z help查看可用的标志列表。

-Z unstable-options是用于启用其他不稳定命令行标志的通用标志。需要的此选项将在下面列出。

某些不稳定的特性需要您，在Cargo.toml指定cargo-features字段。

Alternate Registries

替换(/备用)注册表

备用注册表，允许您使用 crates.io 以外的注册表。

注册表的名称定义在.cargo/config中，registries表格的下面:

[registries]
my-registry = { index = "https://my-intranet:8080/git/index" }

可以在.cargo/credentials添加备用注册表的身份验证信息:

[registries.my-registry]
token = "api-token"

在Cargo.toml里面，您可以使用指定registry字段，让某个依赖项来自哪个注册表。但首先，您需要在文件的顶部包含适当的cargo-features:

cargo-features = ["alternative-registries"]

[package]
...

[dependencies]
other-create = { version = "1.0", registry = "my-registry"}

一个--registry标志 已添加到与注册表交互的publish，login等命令中。示例:

cargo +nightly publish -Z unstable-options --registry my-registry

在Cargo.toml的 publish 字段，已被扩展为接受限制为发布到这些注册表的注册表列表。

[package]
...
publish = ["my-registry"]

publish-lockfile

发布-锁文件

创建.crate文件分发时，Cargo 历史上不包括Cargo.lock文件。这可能会导致cargo install用于二进制文件的问题。您可以在cargo package要么cargo publish使用时，指定您的包应包含Cargo.lock，方法是在Cargo.toml中指定publish-lockfile字段。这也需要适当的cargo-features要求:

cargo-features = ["publish-lockfile"]

[package]
...
publish-lockfile = true

Offline Mode

离线模式

-Z offline标志 可防止 Cargo 因任何原因尝试访问网络。通常情况下，如果 Cargo 要访问网络但它不可用，则会因错误而停止。

请注意，这可能会导致与在线模式不同的依赖项解析。即使可能有索引的较新版本的本地副本，Cargo 也会将自己限制在本地可用的箱(crate)中。

no-index-update

无索引更新

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

avoid-dev-deps

阻止 开发依赖项

运行命令如cargo install要么cargo build时，Cargo 当前会需要下载 dev 依赖项，即使它们未被使用。而该-Z avoid-dev-deps标志 则让 Cargo 避免在不需要时下载 dev 依赖项。该Cargo.lock如果跳过了 dev-dependencies，将不会生成相关信息。

minimal-versions

最小的版本

当一个Cargo.lock文件被生成，-Z minimal-versions标志的使用， 将解析依赖关系为满足要求的最小 semver 版本(而不是最高版本)。

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

out-dir

输出目录

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

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

Profile Overrides

覆盖配置

可以为特定包和自定义生成脚本覆盖配置文件。一般格式如下:

cargo-features = ["profile-overrides"]

[package]
...

[profile.dev]
opt-level = 0
debug = true

# 这个 `image` 箱 会编译的等级 -Copt-level=3
[profile.dev.overrides.image]
opt-level = 3

# 所有 依赖项 (但 不是 箱本身 或 某些工作区成员)
# 会编译的等级 -Copt-level=2 。 其中包括 构建依赖项.
[profile.dev.overrides."*"]
opt-level = 2

# 构建 脚本和他们的 依赖项， 会编译的等级 -Copt-level=3
# 默认情况， 构建 脚本 对剩下的配置使用相同的选择
[profile.dev.build-override]
opt-level = 3

能只为 dev 和 release 配置文件指定覆盖。

Config Profiles

配置 配置文件 (第一个动词，第二个名词)

可以在.cargo/config文件中指定配置文件。该-Z config-profile命令行标志是使用此功能所必需的。格式与一个 Cargo.toml清单格式相同。如果在多个文件中找到相同的配置，则通过使用常规设置配置层次结构合并。配置设置优先于清单设置。

[profile.dev]
opt-level = 3
cargo +nightly build -Z config-profile

Namespaced features

特性的命名区间化

目前，不可能在清单中具有相同名称的特性和依赖项。但如果你设置namespaced-features至true，功能和依赖项的命名空间就会是分开的。这样做的结果是，在特性请求中，依赖项必须以crate:为前缀。像这样:

[package]
namespaced-features = true

[features]
bar = ["crate:baz", "foo"]
foo = []

[dependencies]
baz = { version = "0.1", optional = true }

为了防止不必要的，必须为每个可选依赖项显式声明特性的模版，将为任何不是定义为相同名称的特性，的可选依赖项创建隐式特性。但是，如果定义了与依赖项同名的特性，则该特性必须将依赖项作为必需项，正如foo = ["crate:foo"]。

Build-plan

构建计划

build命令的--build-plan参数，将输出 JSON，其中包含有关将运行哪些命令，和不实际执行任何操作的信息。与其他构建工具集成时，这可能很有用。例:

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

default-run

默认运行

清单中[package]部分的该default-run选项，可用于指定cargo run选择的默认二进制文件。例如，当存在src/bin/a.rs和src/bin/b.rs两者时，选择前者:

[package]
default-run = "a"

Metabuild

元构建

Metabuild 是一个具有声明性构建脚本的特性。作为不去写一个build.rs脚本，而是您在Cargo.toml中的metabuild字段，指定构建依赖项列表。其将自动生成一个构建脚本，该脚本按顺序运行每个构建依赖项。然后，Metabuild 包可以从Cargo.toml中读取元数据，执行他们的指定行为。

需要包括cargo-features在Cargo.toml的顶部， 一个metadata字段在package下，列出build-dependencies依赖项，并添加 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脚本一样，执行相同操作。