Cargo project basic

Posted on Edited on

Cargo basic

Cargo 是 Rust 的 build & package management system，通常會用 Cargo 管理 Rust project。安裝 Rust 會一起裝 Cargo。

這跟 npm、bower、composer 等等 package manager 很像，不過為 Rust 需要 compile，所以 Cargo 除了 package management 還有 build system。package manager 是為了解決各種 library 或 package dependency 的問題，例如像 C/C++ 得自己處理如何 build 跟 link library（還會有只剩 binary 檔不知道 source code 從哪來的 library）、維持 library 版本以及升級 library 等問題。

Cargo 裡稱 package 或 library 為 crate。

Cargo 基本指令：

1
2
3
4
$ cargo build
$ cargo run
$ cargo clean
$ cargo update  # 升級 crate

Start new project

$ cargo new <project name> --bin

產生基本 project 的 directory，內含 src/ 跟 Cargo.toml 並且建立 git repository。加 --bin 是為了 build 出可執行檔，不加會是 library。建立 project 後修改 Cargo.toml 即可，Cargo.toml sample：

1
2
3
4
5
6
[package]
name = "rust-hello-cargo"
version = "0.1.0"
authors = ["cjwind <cwentsai@gmail.com>"]

[dependencies]

Directory structure

1
2
3
4
src/    # source code directory
    xxx.rs
Cargo.toml    # Cargo configuration
Cargo.lock    # Cargo uses the Cargo.lock file to keep track of dependencies

Cargo 會自己維護 Cargo.lock，不須手動修改。

Cargo.toml

Cargo 用 Cargo.toml 來 maintain dependency──需要什麼 crate 以及 crate 版本。這跟 nodejs、PHP 之類的 package management 差不多，只是各自用不同格式而已。

修改 Cargo.toml 之後再 build，Cargo 會去抓需要的 crate 跟處理 dependency──如果 crate 還有 depend 是 project 沒有的也會去抓──然後 compile 它們。

Cargo.lock

假設 project 依賴 crate A 1.0.12，crate A 有新版本 1.0.13 時會怎樣？

如果 Cargo 自動更新 crate 版本，萬一新版 crate A 反而讓我們的程式爛掉怎麼辦？畢竟總是可能有 bug 的，又或者某些介面或功能被修改了、行為跟原本不一樣也可能造成問題。

Cargo 對此的解決方式跟其他 package manager 差不多──使用 Cargo.lock。

第一次 build project 的時候（應該是 dependency 改動過後的第一次），Cargo 會在 Cargo.lock 記下當下 crate 的版本並且認定這些版本是 ok 的。之後即使 crate 有新版本，Cargo 也不會主動去更新而是以 Cargo.lock 記錄的為準，直到我們要求升級 crate。

cargo update 預設只會升最後一碼版號，比較大版本的升級要手動改 Cargo.toml。因為大版本的更新可能會有 interface 的改動，需要我們確認相應修改沒問題才能更新。

延伸閱讀