The Manifest Format

清单格式

每个包的这个Cargo.toml文件称为清单. 每个清单文件由一个或多个部分(表格)组成.

The [package] section

[package]部分

Cargo.toml的第一部分是[package].

[package]
name = "hello_world" # the name of the package
version = "0.1.0"    # the current version, obeying semver
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]

所有这三个字段都是必要性的.

The version field

version 字段

Cargo 烘烤的概念是语义版本控制,所以确保你遵循一些基本规则:

  • 在您达到 1.0.0 之前,任何事情都会发生,但是如果您进行了重大变化的更新,则增加次要(minor)版本。在 Rust 语言中,重大变化包括,向结构添加字段,或增加变量到枚举。
  • 在 1.0.0 之后,只在增加主要(major)版本时进行重大变化。不要破坏建筑.
  • 在 1.0.0 之后,不要在补丁级别(patch)的版本添加任何新的公共 API(没有任何新的pub)。如果添加pub结构、特性、字段、类型、函数、方法或其他任何东东,则总是增加次要版本。
  • 使用具有三个数字部分的版本号,如 1.0.0,而不是 1.0。

The edition field (optional)

edition 字段 (可选)

您可以在Cargo.toml中的edition字段,选择一个特定的 Rust 版本,用于您的包。 如果没有指定版本,它将默认为 2015。

[package]
# ...
edition = '2018'

这个edition字段会影响到您的包编译的版本。若是通过cargo new得来的项目,Cargo 将始终让edition字段设置为最新版本。设置[package]下的edition字段将影响包中的所有目标/箱,包括测试套件、基准、二进制文件、示例等。

The build field (optional)

build 字段 (可选)

此字段指定包根目录中的文件,该文件是构建脚本,用于生成本机代码。可以在构建脚本指导中找到更多信息..

[package]
# ...
build = "build.rs"

The links field (optional)

links 字段 (可选)

此字段指定,要链接到的本机库名,更多信息可以在构建脚本指南的links部分.

[package]
# ...
links = "foo"
build = "build.rs"

The documentation field (optional)

documentation 字段 (可选)

此字段指定托管箱(crate)文档的网站的 URL。如果清单文件中没有指定 URL,crates.io自动将你的箱子连接到相应的箱子的docs.rs页.

来自特定主机的文档链接被列入黑名单。如果已知主机不承载文档,并且可能具有恶意意图,例如广告跟踪网络,则主机被添加到黑名单中。下列主机的 URL 就被列入黑名单:

  • rust-ci.org

来自黑名单主机的文档 URL 将不会出现在 crates.io 上,并且可能被 docs.rs 链接替换。

The exclude and include fields (optional)

excludeinclude 字段 (可选)

出于打包和重建包的目的,您可以显式地指定一组globs模式,匹配项应被忽略或包含。如exclude字段标识了在发布包时,不包括的一组文件,以及检测何时重建包时,应该忽略的文件,而include就是显式指定一定包含的文件。

如果一个 VCS 被用于一个包,则exclude字段将被植入 VCS 的忽略设置(例如 Git 的.gitignore)。

[package]
# ...
exclude = ["build/**/*.o", "doc/**/*.md"]
[package]
# ...
include = ["src/**/*", "Cargo.toml"]

选项是相互排斥的: include设置覆盖exclude。 注意include必须是文件的详尽列表,否则可能不包括必要的源文件。

Migrating to gitignore-like pattern matching

转移成 类gitignore 模式匹配

这些配置的当前解释实现都基于 UNIX Globs,如glob。 若是我们想要 Cargo 的includeexclude尽可能配置为类似于gitignore。可看看这个gitignore规范,其也是基于 Globs 的,但是还有许多其他的特性,这些特性使模式编写更容易,控制也更多。因此,我们正在迁移这些配置规则的解释实现,以使用ignore,并认真对待gitignore文件的每一条行规则。见跟踪问题有关迁移的更多细节。

The publish field (optional)

publish 字段 (可选)

这个publish字段通过错误,防止将包(crate),发布到包注册中心(如crates.io)。

[package]
# ...
publish = false

The workspace field (optional)

workspace 字段 (可选)

这个workspace字段可用于配置此包将属于的工作区。如果没有指定,这将被推断为文件系统中第一个 Cargo.toml 的[workspace]

[package]
# ...
workspace = "path/to/workspace/root"

有关更多信息,请参见下面的工作区(workspace)表格的文档.

Package metadata

包 元信息

[package]部分会接受许多可选的元数据字段:

[package]
# ...

# 关于包的简短介绍. 这不会以任何格式呈现
# 到 crates.io (又名 这不是markdown).
description = "..."

# 这些URL指向有关包的更多信息 这些是
# 旨在成为相关数据的网页入口, 不一定兼容
# VCS工具(类似的)等.
documentation = "..."
homepage = "..."
repository = "..."

# 这指向包根目录下的文件 (与 `Cargo.toml` 相对的).
# 该文件的内容会存储,并在注册表中编入索引。
# crates.io 将渲染此文件,并将结果放在包的页面上.
readme = "..."

# 这是一个,最多五个描述此箱的关键字的列表. 关键词
# 可以在 crates.io 上搜索, 和你可以选择任何单词
# 帮助别人找到这个箱子。
keywords = ["...", "..."]

# 这是此箱子最适合的(最多五个)类别的列表.
# 类别是 crates.io/category_slugs 上可用的固定列表, 和
# 他们必须完全匹配.
categories = ["...", "..."]

# 这是此包的SPDX 2.1许可证表达式.  目前
# crates.io将根据白名单的已知许可证和SPDX许可证列表2.4中的异常标识符,
# 验证提供的许可证。目前不支持括号。
#
# 使用AND和OR的许可证表达式
# 运算符以获得更明确的语义。
license = "..."

# 如果程序包使用非标准许可证, 则可以指定此 key
# 代替上述 key 和 必须指向相对于此清单的文件
# (类似于 readme key).
license-file = "..."

# 要在crates.io上显示的徽章规范,的可选项。
#
#  - 与当前可用的构建状态有关的徽章是
#   Appveyor, CircleCI, GitLab, 和 TravisCI.
# - 与代码测试覆盖有关的可用徽章是 Codecov 和
#   Coveralls.
# - 还有基于 isitmaintained.com的维护相关徽章
#   其中说明了问题解决时间,未决问题的百分比和未来
#   维护意图。
#
# 若要求一个`repository` key, 就表示一个`user/repo` 格式的存储库
[badges]

# Appveyor: `repository` 是必须的. `branch` 是可选的; 默认为 `master`
# `service` 是可选的; 有效值是 `github` (默认), `bitbucket`, 和
# `gitlab`; `id` 是可选的; 如果你想改用,可以指定appveyor 项目ID.
# `project_name` 是可选的; 使用在 repository
# 名称 与 appveyor 项目名称 不同的情况.
appveyor = { repository = "...", branch = "master", service = "github" }

# Circle CI: `repository` 是必须的. `branch` 是可选的; 默认为 `master`
circle-ci = { repository = "...", branch = "master" }

# GitLab: `repository` 是必须的. `branch` 是可选的; 默认为 `master`
gitlab = { repository = "...", branch = "master" }

# Travis CI: `repository`为 "<user>/<project>"格式 是必须的.
# `branch` 是可选的; 默认为 `master`
travis-ci = { repository = "...", branch = "master" }

# Codecov: `repository` 是必须的. `branch` 是可选的; 默认为 `master`
# `service` 是可选的; 有效值是 `github` (默认), `bitbucket`, 和
# `gitlab`.
codecov = { repository = "...", branch = "master", service = "github" }

# Coveralls: `repository` 是必须的. `branch` 是可选的; 默认为 `master`
# `service` 是可选的; 有效值是 `github` (默认) 和 `bitbucket`.
coveralls = { repository = "...", branch = "master", service = "github" }

# 是否保持解决时间: `repository` 是必须的.
is-it-maintained-issue-resolution = { repository = "..." }

# 它是否保持未解决问题的百分比: `repository` 是必须的.
is-it-maintained-open-issues = { repository = "..." }

# Maintenance: `status` 是必须的. 可用的选项是 `actively-developed`,
# `passively-maintained`, `as-is`, `experimental`, `looking-for-maintainer`,
# `deprecated`, 和 默认为 `none`, 不会在 crates.io 显示徽章.
maintenance = { status = "..." }

这个crates.io注册中心将呈现描述、显示许可证、链接到三个 URL 并根据关键字进行分类。这些字段为注册表的用户提供有用的信息,并且还影响箱子的搜索排名。在发布箱的'展示栏',省略任何东西都是非常令人沮丧的。

SPDX 2.1 许可证表达式被记录在案在这里。 许可证列表的当前版本可用的,在这里,版本 2.4 是可用的,在这里.

The metadata table (optional)

metadata 表格 (可选)

默认情况下,Cargo 将对Cargo.toml不使用的字段发出警告,协助检测错别字等。就像这个package.metadata表格,但是,完全不写了的话, Cargo 将不会被警告。这个表格可在Cargo.toml,用于将包配置存储好。 例如:

[package]
name = "..."
# ...

# 当要生成一个 Android APK,这个元信息会被使用, 例如.
[package.metadata.android]
package-name = "my-awesome-android-app"
assets = "path/to/static"

Dependency sections

依赖 部分

指定依赖-那页有关[dependencies][dev-dependencies][build-dependencies]和特定目标的[target.*.dependencies]部分的信息。

The [profile.*] sections

[profile.*] 部分

Cargo 支持了,可通过顶层 配置文件(profile) 调用 rustc 的自定义配置。任何清单都可以声明一个配置文件,但是实际上只读取顶级包的配置文件。所有依赖项的配置文件都将被重写,这样做是为了让顶级包能够控制,其依赖项如何编译的。

目前有四个受支持的配置文件名称,它们都具有相同的配置。下面列出了可用的配置,以及每个配置文件的默认设置.

# 此为 开发配置文件, 给 `cargo build` 所使用.
[profile.dev]
opt-level = 0      # 控制编译器构建的`--opt-level`。
                   # 0-1适合调试。 2是良好优化的。最大为 3。
                   # 's' 企图优化大小, 'z' 则 进一步优化大小.
debug = true       # (u32 or bool) 包括调试信息(调试符号).
                   # 相当于 `-C debuginfo=2` 编译器 标志.
rpath = false      # 控制 编译器 是否应该设置加载器路径.
                   # 若为 true, 传递 `-C rpath` 标志 给 编译器.
lto = false        # 链接时间优化通常会减少二进制文件和静态库的大小
                   # 但会增加编译时间.
                   # 若是 true, 传递 `-C lto` 标志 给 编译器, 和 若是一个
                   # 字符串值 像 'thin' ,那会传递 `-C lto=thin`
                   # 给 编译器
debug-assertions = true # 控制是否启用调试断言
                   # (e.g. debug_assert!() 和 算术溢出检查)
codegen-units = 16 # if > 1 并行代码生成,以改善
                   # 编译时间, 但阻止了些优化.
                   # 传递 `-C codegen-units`.
panic = 'unwind'   # 恐慌策略 (`-C panic=...`), 也可以是 'abort'
incremental = true # 是否启用增量编译
overflow-checks = true # 使用溢出检查进行整数运算。
                   # 传递 `-C overflow-checks=...`标志 给 compiler.

# 发布(release)的配置文件, 用于 `cargo build --release` (和 依赖项的
# `cargo test --release`,  包括本地 library 或 binary).
[profile.release]
opt-level = 3
debug = false
rpath = false
lto = false
debug-assertions = false
codegen-units = 16
panic = 'unwind'
incremental = false
overflow-checks = false

# 测试的配置文件, 用于 `cargo test` (对于 `cargo test --release`,可看
# `release` 和 `bench` 配置文件).
[profile.test]
opt-level = 0
debug = 2
rpath = false
lto = false
debug-assertions = true
codegen-units = 16
panic = 'unwind'
incremental = true
overflow-checks = true

# 基准的配置文件, 用于`cargo bench` (和 要测试的目标 和
# 单元测试的 `cargo test --release`).
[profile.bench]
opt-level = 3
debug = false
rpath = false
lto = false
debug-assertions = false
codegen-units = 16
panic = 'unwind'
incremental = false
overflow-checks = false

The [features] section

[features] 部分

Cargo 支持特性,允许表达:

  • 条件编译选项(通过cfg属性);
  • 可选的依赖项,增强了包,但不是必需的;还有
  • 可选依赖项的簇,如postgres,其中就包括postgrespostgres-macros包,以及可能的其他包(如开发时的模拟库、调试工具等)。

包的特性也可以是可选的依赖项,也可以是一组其他特性。指定特性的格式是:

[package]
name = "awesome"

[features]
# 默认的可选包集。大多数人都想使用这些
# 包, 但它们是严格可选的。请注意,`session`不是包
# 而是此清单中列出的另一个功能。
default = ["jquery", "uglifier", "session"]

# 没有依赖关系的特性,主要用于条件编译,
# 像 `#[cfg(feature = "go-faster")]`.
go-faster = []

# `secure-password` 特性 需要 bcrypt 包. 这种别名
将允许人们以更高级别的方式讨论该 特性 和 允许
# 此软件包将在未来为该特性添加更多要求.
secure-password = ["bcrypt"]

# 特性可用于重新导出其他包的特性. `awesome`包的 `session`
# 特性将确保 cookie/session 也是可用的
session = ["cookie/session"]

[dependencies]
# 这些包是强制性的,是该软件包发行版的核心。
cookie = "1.2.0"
oauth = "1.1.0"
route-recognizer = "=2.1.0"

# 所以可选依赖项的列表, 其中一些是上面的
# `features`. 它们可以通过应用程序选择加入。
jquery = { version = "1.0.2", optional = true }
uglifier = { version = "1.5.3", optional = true }
bcrypt = { version = "*", optional = true }
civet = { version = "*", optional = true }

使用awesome包:

[dependencies.awesome]
version = "1.3.5"
default-features = false # 不包括默认功能,和可选,
                         # 任君选 个性化特性
features = ["secure-password", "civet"]

Rules

规则

特性的使用遵循一些规则:

  • 特性名称不能与清单中的其他包名称冲突。这是因为他们被选择加入features = [...],而它只有一个命名空间。
  • 除此default特性之外,所有的特性都是可选的。若要退出默认功能,请使用default-features = false,任君选择个人特性.
  • 特性群组不允许周期性地相互依赖.
  • 开发 依赖项不能是可选的.
  • 特性群组只能引用可选的依赖项.
  • 当选择一个特性时,Cargo 将调用具有--cfg feature="${feature_name}"rustc。如果包含一个特性群组,那么它将包括所有单独的特性。这可以通过#[cfg(feature = "foo")]在代码中进行测试..

主要注意的是,显露的特性,实际上不激活任何可选的依赖项。这就允许包在不需要新的依赖项的情况下,于内部启用/禁用特性。

Usage in end products

生产终点的用法

该特性的一个主要用例是在最终产品中,指定可选特性。例如,Servo 包可能希望包含可选特性,人们可以在构建时,启用或禁用它。

在这种情况下,Servo 将在Cargo.toml描述特性,且用命令行标志来启用这些特性:

$ cargo build --release --features "shumway pdf"

可以使用--no-default-features,排除默认特性。

Usage in packages

包(库)的用法

在大多数情况下,在库中可选依赖的概念,最好将其表示为顶级应用程序所依赖的单独包。

然而,像 Iron 或 Piston 这样的高级软件包会需要排布多个软件包以便于安装。当前的 Cargo 系统允许它们将一些强制依赖项,整合到一个包中,以便于安装。

在某些情况下,包可能希望为可选依赖项,提供额外的管理:

  • 将多个低层可选依赖项,组合到一个单独的高级特性中;
  • 由包用户指定推荐(或建议)要包括的包;
  • 包括特性(类似secure-password在激励示例中),这只在可选的依赖项可用时才能工作,并且很难实现为单独的包(例如,设计一个与 OpenSSL 完全解耦的 IO 包可能过于困难,那这时,就可通过包含单独的包来选择相关特性)。

在几乎所有情况下,在设计牢固的高级包之外,使用这些特性都是反模式的。如果某个特性是可选的,那么它几乎可以肯定地表示为单独的包。

The [workspace] section

[workspace] 部分

包可以定义一个工作区,它是一组箱,所有箱将共享相同Cargo.lock和输出目录。这个[workspace]表格可以定义为:

[workspace]

# 可选字段,从路径依赖推断(如果不存在)。
# 此处必须给出,包含的其他非路径依赖。
# 特别是, 对于 一个虚拟清单,所有成员都要列出来。
members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]

# 可选字段, 如果不存在则为空
exclude = ["path1", "path/to/dir2"]

工作区作为 Cargo 的RFC 1525一部分被添加到 Cargo 中,并具有许多属性:

  • 工作区可以包含多个箱,其中一个是根箱.
  • 这个根箱Cargo.toml包含[workspace]表格,但不要求必有其他配置.
  • 每当编译工作区中的任何箱时,输出被放置在工作区根。 即紧挨着根箱Cargo.toml.
  • 工作区中所有箱的那个锁定文件驻留在工作区根.
  • Cargo.toml[patch][replace][profile.*]部分,只认根箱的清单,而忽略成员箱的。

这个工作区的根箱,由其清单中存在的[workspace]指定,并负责定义整个工作区。所有驻留在工作区目录中的path依赖项都变成成员。您可以通过members字段将附加包添加到工作区中。请注意,显式列出的工作区成员,也在工作区中包含了它们的路径依赖项。有时候,一个包可能有很多工作区成员,并且都保持最新会很麻烦。

路径依赖也可以使用globs匹配多个路径。 最后,exclude字段 可以用于将工作路径中的路径列入黑名单。如果根本不希望某些路径依赖项存在于工作区中,那么这非常有用.

这个package.workspace清单字段(如上所述)用于成员箱中,以指向工作区的根箱。如果省略此字段,则推断它是文件系统(向上的父目录)中,清单包含[workspace]的第一个箱。

箱可以指定package.workspace或指定[workspace]。 也就是说,箱不能同时作为工作区中的根箱(包含[workspace]),和另一个工作区的成员箱(包含package.workspace)

大多数时间工作区都不需要处理。因cargo newcargo init将自动处理工作区配置。

Virtual Manifest

虚拟清单

在工作区清单中,如果package表格存在,则工作区根箱将被视为普通包和工作区。如果package表格不存在工作区清单中,那它被称为虚拟清单

Package selection

Package 部分

在工作区中,与包相关的 Cargo 命令,如cargo build,会应用-p / --package--all命令行参数选定的包。当未指定时,可选default-members配置被使用:

[workspace]
members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
default-members = ["path/to/member2", "path/to/member3/foo"]

default-members指定时,必会扩展到子集的members中.

若是default-members未指定,如果它是包,则默认为根清单,或者若是虚拟工作区,就为每个成员的清单(如同--all在命令行上).

The project layout

项目布局

如果包是可执行文件,则将主源文件命名为src/main.rs。 如果它是一个库,请命名主源文件src/lib.rs

Cargo 也将处理位于src/bin/*.rs任何文件作为可执行文件。如果可执行文件包含不止一个源文件,则可以使用src/bin目录下,又一个包含main.rs文件的目录,而该目录将被视为具有父目录名称的可执行文件。但是,一旦添加了[[bin]]部分见下文,Cargo 将不再自动建立src/bin/*.rs文件。 相反,你必须创建一个[[bin]]部分,给出你想要生成的每个文件。

您的包可以(可选地)包含命名为examplestestsbenches文件夹,Cargo 将分别将其视为包含示例、集成测试和基准。类似于bin目标,它们可以由单个文件或拥有main.rs文件的目录组成。

▾ src/           # 包含源文件的目录
  lib.rs         # 库和包的主要入口点
  main.rs        # 包生成可执行文件的主要入口点
  ▾ bin/         # (可选)包含其他可执行文件的目录
    *.rs
  ▾ */           # (可选)包含多文件可执行文件的目录
    main.rs
▾ examples/      # (可选)示例
  *.rs
  ▾ */           # (可选)包含多文件示例的目录
    main.rs
▾ tests/         # (可选)集成测试
  *.rs
  ▾ */           # (可选)包含多文件测试的目录
    main.rs
▾ benches/       # (可选)基准
  *.rs
  ▾ */           # (可选)包含多文件基准的目录
    main.rs

为了在创建文件和文件夹之后,为包构造代码,应该记住使用 Rust 的模块系统,您可以在这本找到。

(译):中文

Examples

示例

位于examples下方的文件,是库提供的功能示例用法。编译时,它们被放置在target/examples目录。

它们可以编译为可执行文件(用main()函数)或,库。和可通过使用extern crate <library-name>导入库。 当您运行测试以保护它们免遭篡改时,它们会被编译。

可以使用命令cargo run --example <example-name>运行单个可执行示例.

指定crate-type将示例编译为库(有关箱类型的附加信息可在Rust 参考找到):

[[example]]
name = "foo"
crate-type = ["staticlib"]

可以使用命令cargo build --example <example-name>构建单个库实例.

Tests

测试

当你运行cargo test,Cargo 会:

  • 编译并运行库的单元测试,这些测试位于lib.rs(当然,任何标记为#[cfg(test)]部分将考虑为同个阶段);
  • 编译并运行嵌入到文档区块内部的库的文档测试;
  • 编译并运行您库的集成测试
  • 编译你库的例子.

Integration tests

集成测试

tests/*.rs的每个文件是一个集成测试。当你运行cargo test,Cargo 将编译每个文件作为一个单独的箱子。箱可以通过使用extern crate <library-name>链接(导入)您的库,就像其他导入项一样。

Cargo 不会自动编译tests子目录内的文件,但是,集成测试可以像往常一样从这些目录导入模块。例如,如果希望多个集成测试共享一些代码,可以将共享代码放入tests/common/mod.rs,然后为每个测试文件添加mod common;

Configuring a target

配置为一个目标

所有的[[bin]][lib][[bench]][[test]][[example]]部分都支持类似的配置,用于指定应该如何构建目标。双括号[[bin]]部分,是TOML格式的数组。这意味着你可以在您的箱中写多个[[bin]],这样就会生成几个可执行文件。

下面的例子使用[lib],但它也适用于所有其他部分。除非另有说明,下面所有列出的值都是对应选项的默认值

[package]
# ...

[lib]
# 生成目标与库的名称. 本该默认是
# 包名, 替换所有破折号
# 为 下划线. (Rust `extern crate` 声明会参考该名;
# 因此,该值必须是可用的有效Rust标识符.)
name = "foo"

# 该字段,指向 crate 的入口(位置), 路径相对于 `Cargo.toml`.
path = "src/lib.rs"

# 一个给目标启用单元测试 的 标志. 会被 `cargo test`使用.
test = true

# 一个给目标启用文档测试 的 标志. 只与库相关
# , 不会影响其他部分。会被
# `cargo test`使用.
doctest = true

# 一个给目标启用基准 的 标志. 会被 `cargo bench`使用.
bench = true

# 一个给目标启用文档 的 标志. 会被 `cargo doc`使用.
doc = true

# 若该目标为 编译器扩展, 那要把该字段设为 true
# ,以让 Cargo 正确编译和,可用于所有依赖项.
plugin = false

# 若该目标为 "macros 1.1" 程序宏, 那要把该字段设为 true
proc-macro = false

# 若设为 false, `cargo test` 会为 rustc 省略 `--test` 标志, 这
# 阻止它生成测试工具 这在二进制存在,
# 构建管理测试运行器本身的情况下,有用.
harness = true

# 若设置了,那 目标会使用一个与`[package]`配置不同的版本
# , 也许是,编译一个库
2018年版本或,编译单元测试的2015年版本. 默认情况下
# 所有目标都使用`[package]`中指定的版本进行编译。
edition = '2015'

这个[package]还包括可选的autobins,autoexamples,autotestsautobenches,来明确 进入/退出 自动发现特定的目标种类。

The required-features field (optional)

required-features 字段 (可选)

这个required-features字段指定目标需要构建的特性。如果未选择任何所需的特性,则将跳过目标。这只与[[bin]][[bench]][[test]][[example]]部分有影响,它没有影响[lib]

[features]
# ...
postgres = []
sqlite = []
tools = []

[[bin]]
# ...
required-features = ["postgres", "tools"]

Building dynamic or static libraries

构建 动态 或 静态 库

如果您的包生成一个库,则可以通过在Cargo.toml显式地指明构建的库类型:

# ...

[lib]
name = "..."
crate-type = ["dylib"] # 也能是 `staticlib`

可用的选项是dylibrlibstaticlibcdylibproc-macro。 您应该只在包中使用一次此选项。Cargo 总是根据(包括的)包的要求来编译包(依赖项)。

您可以阅读Rust 参考手册中更多关于不同的箱类型

The [patch] Section

[patch] 部分

这部分可以用来重写其他副本的依赖项。语法类似于[dependencies]部分:

[patch.crates-io]
foo = { git = 'https://github.com/example/foo' }
bar = { path = 'my/local/bar' }

[dependencies.baz]
git = 'https://github.com/example/baz'

[patch.'https://github.com/example/baz']
baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }

这个[patch]表格由,类似依赖表格的子表组成。[patch]后的每个字段是正在修补的源 URL,或者crates-io(如果你正在修改HTTPS://CRATESIO注册表)。在上面的例子中,crates-io可以用 Git URL 替换,例如https://github.com/rust-lang-nursery/log;第二个示例中的[patch]部分使用此来指定一个名为baz的源。

这些表格中的每个项都是一个正常的依赖关系规范,与[dependencies]清单的部分一样。[patch]部分中列出的依赖项,被解析并用于在指定的 URL 上对源进行补丁。上面的清单片段补丁crates-io源(例如 crates.io 本身)的foo箱和bar箱。它也用一个来自其他地方的my-branch分支修补了https://github.com/example/baz源。

可以用不存在的箱版本来修补源,也可以用已经存在的箱版本来修补源。如果用源中已经存在的箱版本对源进行修补,则会替换源的原始箱。

有关重写依赖关系的更多信息,可阅读本文档的重写依赖项章节和对于这一特性的RFC 1969技术规范说明。

The [replace] Section

[replace] 部分

这部分可以用来重写其他副本的依赖项。语法类似于[dependencies]部分:

[replace]
"foo:0.1.0" = { git = 'https://github.com/example/foo' }
"bar:1.0.2" = { path = 'my/local/bar' }

[replace]表格的每个字段都是包标识规范,它任意选择依赖图中的节点来重写。每个字段值与`[dependencies]指定依赖关系的语法是一样,除了不能指定特性。注意,当覆盖一个箱时,覆盖它的副本必须具有相同的名称和版本,但它可以来自不同的源(例如,git 或本地路径).

有关重写依赖关系的更多信息,可阅读本文档的重写依赖项章节。