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 warningsLinter 检查错误
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
  • --bin 正在制作一个二进制程序
  • --lib 正在创建一个库(lib)

得到如下目录:

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

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

[package]
name = "hello_world"
version = "0.1.0"
authors = ["Your Name <[email protected]>"]
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]
  • --bin 创建具有二进制目标 (src/main.rs) 的包(默认行为)
  • --lib 使用库目标 (src/lib.rs) 创建一个包
  • --edition edition 指定要使用的 Rust 版本。默认值为 2021。可能的值：2015、2018、2021
  • --name name 设置包名。默认为目录名称
  • --vcs vcs 为给定的版本控制系统（git、hg、pijul 或fossil）初始化一个新的 VCS 存储库，或者根本不初始化任何版本控制（无）
  • --registry registry 限制仅发布到该注册表
$ cargo new foo

安装包

# 从 crates.io 安装或升级软件包：
$ cargo install ripgrep
# 在当前目录安装或重新安装包：
$ cargo install --path .
# 查看已安装包的列表：
$ cargo install --list
  • --vers version
  • --version version 指定要安装的版本
  • --git url 用于安装指定 crate 的 Git URL
  • --branch branch 从 git 安装时要使用的分支
  • --tag tag 从 git 安装时使用的标记
  • --rev sha 从 git 安装时使用的特定提交
  • --path path 要安装的本地 crate 的文件系统路径
  • --list 列出所有已安装的软件包及其版本
  • -f, --force 强制覆盖现有的 crate 或二进制文件

搜索包

$ cargo search [options] [query...]
  • --limit limit 限制结果数量(默认值：10，最大值：100)
  • --index index 要使用的注册表索引的 URL
  • --registry registry 要使用的注册表的名称
$ cargo search serde

卸载包

$ cargo uninstall [options] [spec...]
  • -p, --package spec... 要卸载的软件包
  • --bin name... 仅卸载二进制名称
  • --root dir 从中卸载软件包的目录
$ 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

打包 & 发布公共选项

选择包

  • -p spec..., --package spec... Package 指定包
  • --workspace Package 工作区中的全体成员
  • --exclude SPEC... 排除指定包

编译选项

  • --target triple 为指定架构执行 Package
  • --target-dir directory 用于存放生成的工件以及中间文件的目录

特性选择

  • --features features 传递以空格或者逗号分隔的列表，其中给出要启用的特性
  • --all-features 为给定的包启用全部可用特性
  • --no-default-features 不启用给定包的default特性

清单选项

  • --manifest-path path 用于指定 Cargo.toml 文件的路径
  • --frozen, --locked 这两个选项用于保证Cargo.lock文件是最新的
  • --offline 禁止Cargo访问网络

混杂选项

  • -j N, --jobs N 要并行运行的作业数量

打包

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

$ cargo package [options]
  • -l, --list 输出包中包含的文件(不实际进行打包)。
  • --no-verify 构建包时不进行校验。
  • --no-metadata 忽略 缺少可读的元信息(如描述信息或采用的授权协议) 时产生的警告。
  • --allow-dirty 允许打包 在版本控制系统中仍有未提交内容 的包。

发布

$ cargo publish [options]

发布选项

  • --dry-run 在不上传的情况下执行所有检查
  • --token token 身份验证时使用的 API 令牌
  • --no-verify 不要通过构建内容来验证内容
  • --allow-dirty 允许打包具有未提交的 VCS 更改的工作目录
  • --index index 要使用的注册表索引的 URL
  • --registry registry 要发布到的注册表的名称

打包选择

  • -p spec, --package spec 要发布的包

yank

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

$ cargo yank --vers 1.0.7 foo
  • --vers version 要 yank 或 un-yank 的版本
  • --undo 撤消 yank，将版本放回索引中
  • --token token 身份验证时使用的 API 令牌
  • --index index 要使用的注册表索引的 URL
  • --registry registry 要使用的注册表名称

另见