cargo manifest规则使用介绍

Cargo

Cargo 是一个工具，允许 Rust 项目声明其各种依赖项，并确保您始终获得可重复的构建。

为了实现这一目标，Cargo 做了四件事:

引入两个，包含各种项目信息的元数据文件。
获取，并构建项目的依赖项.
正确使用参数，以调用 rustc 或其他构建工具，构建你的项目。
介绍，更容易使用 Rust 项目的约定 (规范 / 风格)。

Cargo.toml 与 Cargo.lock

Cargo.toml 是从广义上描述你的依赖，并由你编写. Cargo.lock 包含有关您的依赖项的确切信息。它由 Cargo 维护，不应手动编辑.

Cargo.toml

Cargo.toml是一个manifest(清单)，我们可以在其中指定一系列关于我们项目的不同元数据的文件。

从广义上描述我们需要的依赖，并由我们编写.

例如：

[package]
name = "hello_world"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]

[dependencies]
rand = { git = "https://github.com/rust-lang-nursery/rand.git" }

上面这个项目有一个依赖关系rand箱。

在这种情况下，依赖于 GitHub 上的特定 Git 存储库。

由于以上代码未指定任何其他信息，因此 Cargo 假定我们打算使用最新提交的master分支构建我们的项目。

cargo的语法规则

包

[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>"]

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

edition 字段 (可选)

选择一个特定的 Rust 版本，用于您的包。如果没有指定版本，它将默认为 2015。 edition 字段会影响到您的包编译的版本。

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

build 字段 (可选)

指定包根目录中的文件，该文件是构建脚本，用于生成本机代码。

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

构建脚本 build 命令应执行的 Rust 文件 (相对于包根)，将在包编译其他内容之前，被编译和调用，从而具备 Rust 代码所依赖的构建或生成的工件。默认情况下 Cargo 在包根文件中寻找 "build.rs".

links 字段 (可选)

指定要链接到的本机库名.

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

exclude和include 字段 (可选)

出于打包和重建包的目的使用。

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

publish 字段 (可选)

通过false，防止将包 (crate)，发布到包注册中心 (如 crates.io)。

[package]

[package]
# ...
publish = false

workspace 字段 (可选)

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

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

包元字段 (可选)

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

[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 = "..." }

[profile.*] 部分

通过顶层配置文件 (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

依赖指定

默认情况下，Cargo 是准备好，在crates.io上查找依赖项。在这种情况下，只需要名称和版本字符串。

例如：

[dependencies]
time = "0.1.12"

[patch]是[dependencies]的连带关系：

[dependencies]
uuid = "1.0.1"

[patch.crates-io]
uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }

表明uuid的路径。

开发依赖

[dev-dependencies] 编译用于构建的包时，不会使用 Dev 依赖，但用于编译测试，示例和基准。

这些依赖关系是不会传播到依赖于此包的其他包.

使用例子：

[dev-dependencies]
tempdir = "0.3"

构建依赖

[build-dependencies] 在构建脚本中使用，依赖其他基于 Cargo 的箱。使用例子：

[build-dependencies]
cc = "1.0.3"

工作空间

[workspace] 工作区，与包相关的 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"]

程序实例

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

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

参考

Cargo.toml 与 Cargo.lock