本文內容
這篇文章是實戰性質的,也就是說原理部分較少,屬於經驗總結,rust對於模組的例子太少了。rust特性比較多(悲),本文的內容可能只是一部分,實現方式也不一定是這一種。
關於 rust 模組的相關內容,準確來說:怎麼在原始碼中引用其他模組的內容。
- 關於
mod
、use
、as
這幾個關鍵字(檔名) - 關於
mod.rs
檔案 - 關於
self
、super
、crate
這幾個路徑關鍵字 worksapce
:本文不討論,狹義上指的是cargo的[workspace]
部分: 可參見 The [workspace] sectionpackage
: 狹義上指的是cargo的[package]
部分,參見 The [package] sectioncrate
:參見下文 關於 create 的定義和 cargo 管理下的 cratemodule
:本文的重點, crate 裡 會有多個 module,文字討論重點就是 mod 之間相互引用的問題。
一、mod 關鍵字和 mod.rs 檔案,其他普通檔案 foo.rs 等
引用模組要搞清楚的:
- 是在哪裡引用的,也就要引用的檔案的位置
- 需要引用那個模組,跟這個檔案的相對位置和絕對位置是什麼
mod
關鍵字:
- 用來宣告,表現方式是包裹一個程式碼塊。也就是說這個程式碼塊會成為一個單獨的模組。
mod xxx { <rust語句塊> }
:內部寫 rust 語句 。見 例一#[path="...xxxx.rs"] mod xxx;
:使用 path 屬性 ,使用見例二mod xxx { include!("...xxxx.rs") }
:內部配合include!
宏,使用見例二
- 用來宣告(“引用”)其他“模組”。(一個檔案隱含的表示為一個mod)
假設使用mod toy;
語句來引入一個模組,實際上這跟你在哪裡寫的這個語句有關係有關- 把當前的檔案所在位置分為兩類, 型別A:位置在
src/main.rs
、src/lib.rs
或者xxx/.../mod.rs
位置上的檔案; 型別B: 位置不在1中的檔案。 - 在位置型別 A 的檔案使用程式碼
mod toy;
,你實際上在告訴編譯器,你需要的模組是與此檔案同級的toy.rs
或者toy/mod.rs
檔案 。編譯器會自己找下這兩個被引用的位置,如果兩個位置都有檔案,則報錯。見 例三 - 在位置型別 B 的檔案使用程式碼
mod toy;
,你實際上在告訴編譯器,你需要的模組是與此檔案(假設檔名為foo.rs
)同級的foo
資料夾下的foo/toy.rs
或者foo/toy/mod.rs
檔案。編譯器會自己找下這兩個被引用的位置,如果兩個位置都有檔案,則報錯。 見 例四
- 把當前的檔案所在位置分為兩類, 型別A:位置在
二、使用 use 和 as 關鍵字縮短匯入語句,或者匯出模組內容
use
關鍵字也有兩個作用
- 縮短語句,使用 use 為當前檔案縮短長語句,減少重複性的程式碼,見 例子五
- 配合
as
關鍵字一起使用,進一步減少重複程式碼,或者防止名字重複,或者取個順眼的名字 例子六 - 打包其他模組的內容,當做本模組的內容一起匯出。見 例子七
三、使用 super 和 crate 進行相對路徑和絕對路徑(頂級路徑)的訪問
如果我們想要呼叫一個函式,我們需要知道它的路徑。路徑有兩種形式:
- 絕對路徑(absolute path)從 crate 根部開始,以 crate 名或者字面量 crate 開頭。 見例八
- 相對路徑(relative path)從當前模組開始,以 self、super 或當前模組的識別符號開頭。
見文件: https://rustwiki.org/zh-CN/book/ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html
四、關於 create 的定義和 cargo 管理下的 crate
我們都知道透過 cargo 建立出的工程中 src/main.rs
就是程式的入口,但是還有更多的使用方式。
- rustc 命令 : rust編譯器,就算沒有cargo也可以生成程式,但是比較麻煩,這些都讓cargo來處理就好
- cargo 命令 : 專案管理工具
下面就是一些問題了
- 什麼是 create ? rustc 的編譯入口檔案,這個檔案就被當做 crate 檔案。
- crate 型別: 有多種,最常見的是
bin
和lib
,其他型別參見 rust參考手冊-連結 - cargo 怎麼定義工程專案中哪些是需要編譯的 crate 的? 參見: cargo手冊-專案佈局
▾ src/ # 包含原始檔的目錄
lib.rs # 庫和包的主要入口點
main.rs # 包生成可執行檔案的主要入口點
▾ bin/ # (可選)包含其他可執行檔案的目錄
*.rs
▾ */ # (可選)包含多檔案可執行檔案的目錄
main.rs
▾ examples/ # (可選)示例
*.rs
▾ */ # (可選)包含多檔案示例的目錄
main.rs
▾ tests/ # (可選)整合測試
*.rs
▾ */ # (可選)包含多檔案測試的目錄
main.rs
▾ benches/ # (可選)基準
*.rs
▾ */ # (可選)包含多檔案基準的目錄
main.rs
五、例子
例一:單檔案,主函式和 toy
模組
- 注意
run
函式需要加pub
關鍵字,否則不會被匯出
src/main.rs
mod toy {
pub fn run() {
println!("run toy");
}
}
fn main() {
toy::run();
}
輸出
run toy
例二:兩個檔案,主函式和另一個資料夾 toy
模組
src/toy_implements.rs
pub fn run() {
println!("run toy_impl !");
}
src/main.rs
mod toy1 { // 方法1: 使用 include!
include!("./toy_implements.rs");
}
#[path ="./toy_implements.rs"]
mod toy2; // 方法2: 使用 path 屬性定位檔案位置
fn main() {
toy1::run();
toy2::run();
}
輸出
run toy_impl !
run toy_impl !
例三:在 main.rs 中使用 mod toy;
src/toy.rs
pub fn run() {
println!("run toy_impl !");
}
src/main.rs
mod toy;
fn main() {
toy::run();
}
輸出
run toy_impl !
例四:在 src/foo.rs 中使用 mod toy;
src/foo/toy.rs
pub fn run() {
println!("run toy_impl !");
}
src/foo.rs
mod toy;
fn say_hi() {
toy::run();
}
輸出
run toy_impl !
例五:use 指令
之前,我們使用了 toy::run()
來呼叫 run
函式。現在,我們使用 use
關鍵字來匯入 toy
模組裡的內容,這樣就能在 main
函式中直接使用
src/foo.rs
mod toy {
pub fn run() { // 注意使用 pub 關鍵字
println!("run toy");
}
}
fn main() {
use toy::*; // 使用 use 匯入 toy 模組裡的內容
run(); // 直接呼叫
}
例六: 在as配合use指令
src/foo.rs
mod toy {
pub fn run() { // 注意使用 pub 關鍵字
println!("run toy");
}
}
fn main() {
use toy::run as toy_run; // 使用 use + as 匯入 toy 模組裡的內容
toy_run();
}
例七: 使用pub use命令在mod.rs合併打包其他模組的東西
src/toy/runner.rs
pub fn dog_run() { println!("dog is run !"); }
src/toy/fly.rs
pub fn fly_bird() { println!("bird is fly !"); }
src/toy/bear.rs
pub fn bear_eat() { println!("bear is eat fish !"); }
pub fn bear_sleep() { println!("bear is go sleep !"); }
src/toy/mod.rs
mod runner; // 引入同級 runner.rs 檔案
mod fly; // 引入同級 fly.rs 檔案
mod bear; // 引入同級 bear.rs 檔案
pub use runner::dog_run; // 宣告(匯出) dog_run 函式
pub use fly::fly_bird as now_fly_brid; // 宣告(匯出) fly_bird 函式,並重新命名為 now_fly_brid
pub use bear::*; // 宣告(匯出) dog_run 函式
src/main.rs
mod toy;
fn main() {
toy::dog_run();
toy::now_fly_brid();
toy::bear_eat();
toy::bear_sleep();
}
輸出
dog is run !
bird is fly !
bear is eat fish !
bear is go sleep !
例七: 使用pub mod匯出內部包,使用 crate 引用頂部內容
src/toy/cube/mod.rs
pub fn get_size() {
println!("size is in main");
crate::top_size(); // 必不可少的 crate 關鍵字
}
src/toy/mod.rs
pub mod cube;
src/main.rs
mod toy;
fn top_size() {
println!("top size one !")
}
fn main() {
toy::cube::get_size();
}
輸出
size is in main
top size one !
參考文獻
!!強烈推薦看下面的參考做補充!!
- 模組的官方參考: https://rustwiki.org/zh-CN/reference/items/modules.html
- Rust 程式設計語言(7. 使用包、Crate和模組管理不斷增長的專案): https://rustwiki.org/zh-CN/book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html
- Rust 模組和檔案(譯文): https://zhuanlan.zhihu.com/p/73544030
- Rust 模組和檔案(原文): https://amos.me/blog/2019/rust-modules-vs-files/
- crate: https://rustwiki.org/zh-CN/rust-by-example/crates.html
- crate 型別: https://rustwiki.org/zh-CN/reference/linkage.html