Cargo文档

此快速参考备忘清单 Cargo 提供了编译 Rust 常用命令和示例

入门

安装/升级 Rust 和 Cargo

$ curl -sSf https://static.rust-lang.org/rustup.sh | sh

在 Linux 和 macOS 系统上，这可以通过以上方命令完成

命令说明

:- :-
cargo version 显示版本信息以确认 Cargo 已安装
cargo new 创建一个新项目
cargo test 在项目中运行单元测试
cargo check 快速编译项目，无需生成二进制文件来检查错误
cargo fmt 自动格式化代码
cargo build 编译一个项目
cargo run 一步编译和运行项目
cargo clippy --all-targets -- --D warnings Linter 检查错误
cargo tarpaulin --ignore-tests 检查代码覆盖率

切换源

$ touch ~/.cargo/config # 添加配置文件
$ vim ~/.cargo/config   # 编辑配置文件

配置文件 config 内容

[source.crates-io]
registry = "https://github.com/rust-lang/crates.io-index"
replace-with = 'tuna' # 👈 如果需要提交包注释配置源

[source.tuna]
registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git"
# registry = "git://mirrors.ustc.edu.cn/crates.io-index"

💥 注意切换源需要删除缓存目录

$ rm -rf ~/.cargo/.package-cache   # ⚠️ 删除缓存目录内容

创建新项目

$ cargo new hello_world --bin

得到如下目录:

$ cd hello_world
$ tree .
.
├── Cargo.toml
└── src
    └── main.rs

Cargo.toml 被称为一个 manifest 元清单，它包含了 Cargo 编译项目所需的所有元数据

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

[dependencies]

入口文件 src/main.rs

fn main() {
    println!("Hello, world!");
}

运行编译生成 hello_world 二进制文件

$ cargo build
# 文件放入 `target/release` 目录
$ cargo build --release

然后运行它:

$ ./target/debug/hello_world
Hello, world!

也可以直接使用 cargo run，它会自行编译并运行它:

$ cargo run
   Running `target/hello_world`
Hello, world!

来源配置

# `source` 表下，就是存储有关要更换的来源名称
[source]

# 在`source` 表格之下的，可为一定数量的有关来源名称. 示例下面就，定义了一个新源， 叫 `my-awesome-source`，其内容来自本地，`vendor`目录 ，其相对于包含 `.cargo/config` 文件的目录
[source.my-awesome-source]
directory = "vendor"

# Git sources 也指定一个 branch/tag/rev
git = "https://example.com/path/to/repo"
# branch = "master"
# tag = "v1.0.1"
# rev = "313f44e8"

# crates.io 默认源 在"crates-io"名称下，且在这里我们使用 `replace-with` 字段指明 默认源更换成"my-awesome-source"源
[source.crates-io]
replace-with = "my-awesome-source"

编译测试

# 编译输出二进制文件，放入 `target/debug` 目录
$ cargo build
# 输出二进制文件，放入 `target/release` 目录
$ cargo build --release
$ cargo run      # 编译并运行

测试

$ cargo test     # 运行你的所有测试
# 指定函数过滤器
$ cargo test test_foo # 开头是 test_foo 的函数都会运行，例如(test_foo_bar)
# 指定特定模块中的测试函数(通常可以简写 cargo test foo::bar::tests::test_foo)
$ cargo test --package rustt --lib -- foo::bar::tests::test_foo --exact --nocapture

# 指定特定测试的模块(通常可以简写 cargo test foo::bar::tests)
$ cargo test --package rustt --lib -- foo::bar::tests --nocapture

配置目标

[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'

项目目录

.
├── Cargo.lock
├── Cargo.toml
├── benches     # 基准目录
│   └── large-input.rs
├── examples    # 示例
│   └── simple.rs
├── src         # 源代码
│   ├── bin
│   │   └── another_executable.rs
│   ├── lib.rs  # 默认库
│   └── main.rs # 入口文件
└── tests       # 集成测试
    └── some-integration-tests.rs

配置

# 每个源都有自己的表格，名称即是表名
[source.the-source-name]

# 命令 `the-source-name` 会被 `another-source`取代
replace-with = "another-source"

# 有几种可用的源定义(接下来有所描述)
registry = "https://example.com/path/to/index"
local-registry = "path/to/registry"
directory = "path/to/vendor"

更换源的配置通过完成 .cargo/config，上面是全套可用字段

包相关命令

init/new

创建一个新的 cargo 包

$ cargo init [options] [path]
$ cargo new [options] [path]

$ cargo new foo

安装包

# 从 crates.io 安装或升级软件包：
$ cargo install ripgrep
# 在当前目录安装或重新安装包：
$ cargo install --path .
# 查看已安装包的列表：
$ cargo install --list

搜索包

$ cargo search [options] [query...]

$ cargo search serde

卸载包

$ cargo uninstall [options] [spec...]

$ cargo uninstall ripgrep

发布命令

登录

$ cargo login [options] [token]
:- :-
--registry 要使用的注册表的名称
:- :-
-v, --verbose 启用更加详细的输出
-q, --quiet 不输出Cargo的日志信息
--color when 输出内容的颜色 auto, always, never

所有者

# 列出包的所有者：
$ cargo owner --list foo
# 邀请所有者加入包：
$ cargo owner --add username foo
# 从包中删除所有者：
$ cargo owner --remove username foo
:- :-
--token token 身份验证时使用的 API 令牌
--index index 要使用的注册表索引的 URL

打包 & 发布公共选项

选择包

编译选项

特性选择

清单选项

混杂选项

打包

将本地包打包为可分发的压缩文件

$ cargo package [options]

发布

$ cargo publish [options]

发布选项

打包选择

yank

从服务器的索引中删除以前发布的 crate 版本

$ cargo yank --vers 1.0.7 foo

另见