เวิร์กสเปซของ Cargo
ในบทที่ 12 เราได้สร้างแพ็กเกจที่ประกอบด้วยเครตไบนารีและเครตไลบรารี เมื่อโปรเจกต์ของคุณเติบโตขึ้น คุณอาจพบว่าเครตไลบรารีเริ่มมีขนาดใหญ่ขึ้นเรื่อย ๆ จนคุณต้องการแยกแพ็กเกจออกเป็นเครตไลบรารีหลายตัว Cargo มีฟีเจอร์ที่เรียกว่า_เวิร์กสเปซ (workspaces)_ ซึ่งช่วยจัดการแพ็กเกจที่เกี่ยวข้องกันหลายแพ็กเกจและพัฒนาควบคู่กันไปได้
การสร้างเวิร์กสเปซ
เวิร์กสเปซ (workspace) คือชุดของแพ็กเกจที่แชร์ไฟล์ Cargo.lock และไดเรกทอรีเอาต์พุตเดียวกัน มาสร้างโปรเจกต์ที่ใช้เวิร์กสเปซกัน โดยเราจะใช้โค้ดตัวอย่างแบบเรียบง่าย เพื่อให้โฟกัสที่โครงสร้างของเวิร์กสเปซได้อย่างเต็มที่ การจัดโครงสร้างเวิร์กสเปซมีได้หลายวิธี ในที่นี้เราจะแสดงวิธีหนึ่งที่นิยมใช้กัน เราจะสร้างเวิร์กสเปซที่มีไบนารีหนึ่งตัวและไลบรารีสองตัว โดยไบนารีซึ่งทำหน้าที่หลักจะพึ่งพาไลบรารีทั้งสอง ตัวหนึ่งมีฟังก์ชัน add_one และอีกตัวมีฟังก์ชัน add_two เครตทั้งสามตัวนี้จะอยู่ร่วมกันในเวิร์กสเปซเดียวกัน เราจะเริ่มด้วยการสร้างไดเรกทอรีใหม่สำหรับเวิร์กสเปซ:
$ mkdir add
$ cd add
ถัดมา ในไดเรกทอรี add เราจะสร้างไฟล์ Cargo.toml เพื่อกำหนดค่าให้กับทั้งเวิร์กสเปซ ไฟล์นี้จะไม่มีเซกชัน [package] แต่จะเริ่มต้นด้วยเซกชัน [workspace] ซึ่งช่วยให้เราเพิ่มสมาชิก (members) เข้ามาในเวิร์กสเปซได้ นอกจากนี้เรายังเลือกใช้อัลกอริทึม resolver เวอร์ชันล่าสุดของ Cargo ในเวิร์กสเปซของเรา โดยกำหนดค่า resolver เป็น "3":
ชื่อไฟล์: Cargo.toml
[workspace]
resolver = "3"
จากนั้น เราจะสร้างเครตไบนารี adder โดยรัน cargo new ภายในไดเรกทอรี add:
$ cargo new adder
Created binary (application) `adder` package
Adding `adder` as member of workspace at `file:///projects/add`
การรัน cargo new ภายในเวิร์กสเปซจะเพิ่มแพ็กเกจที่เพิ่งสร้างใหม่เข้าไปในคีย์ members ของนิยาม [workspace] ในไฟล์ Cargo.toml ของเวิร์กสเปซให้โดยอัตโนมัติ ดังนี้:
[workspace]
resolver = "3"
members = ["adder"]
ณ จุดนี้ เราสามารถบิลด์เวิร์กสเปซได้โดยรัน cargo build โดยโครงสร้างไฟล์ในไดเรกทอรี add ของคุณควรมีหน้าตาดังนี้:
├── Cargo.lock
├── Cargo.toml
├── adder
│ ├── Cargo.toml
│ └── src
│ └── main.rs
└── target
เวิร์กสเปซจะมีไดเรกทอรี target เพียงแห่งเดียวอยู่ที่ระดับบนสุดสำหรับเก็บอาร์ติแฟกต์ที่คอมไพล์แล้ว โดยแพ็กเกจ adder จะไม่มีไดเรกทอรี target เป็นของตัวเอง และแม้ว่าเราจะรัน cargo build จากภายในไดเรกทอรี adder อาร์ติแฟกต์ที่คอมไพล์แล้วก็ยังคงถูกวางไว้ใน add/target ไม่ใช่ add/adder/target ที่ Cargo จัดโครงสร้างไดเรกทอรี target ในเวิร์กสเปซเช่นนี้ ก็เพราะเครตต่าง ๆ ในเวิร์กสเปซถูกออกแบบมาให้พึ่งพากันเอง หากแต่ละเครตมีไดเรกทอรี target แยกเป็นของตัวเอง แต่ละเครตก็จะต้องคอมไพล์เครตอื่น ๆ ในเวิร์กสเปซซ้ำใหม่เพื่อนำอาร์ติแฟกต์มาไว้ในไดเรกทอรี target ของตนเอง การแชร์ไดเรกทอรี target ร่วมกันจึงช่วยหลีกเลี่ยงการคอมไพล์ซ้ำซ้อนโดยไม่จำเป็น
การสร้างแพ็กเกจที่สองในเวิร์กสเปซ
ถัดมา มาสร้างแพ็กเกจสมาชิกอีกตัวในเวิร์กสเปซและตั้งชื่อว่า add_one โดยสร้างเป็นเครตไลบรารีใหม่:
$ cargo new add_one --lib
Created library `add_one` package
Adding `add_one` as member of workspace at `file:///projects/add`
ตอนนี้ไฟล์ Cargo.toml ระดับบนสุดจะรวมพาธ add_one ไว้ในรายการ members เรียบร้อยแล้ว:
ชื่อไฟล์: Cargo.toml
[workspace]
resolver = "3"
members = ["adder", "add_one"]
ไดเรกทอรี add ของคุณตอนนี้ควรมีไดเรกทอรีและไฟล์ดังต่อไปนี้:
├── Cargo.lock
├── Cargo.toml
├── add_one
│ ├── Cargo.toml
│ └── src
│ └── lib.rs
├── adder
│ ├── Cargo.toml
│ └── src
│ └── main.rs
└── target
ในไฟล์ add_one/src/lib.rs เราจะเพิ่มฟังก์ชัน add_one ดังนี้:
ชื่อไฟล์: add_one/src/lib.rs
pub fn add_one(x: i32) -> i32 {
x + 1
}
ตอนนี้เราสามารถกำหนดให้แพ็กเกจ adder ซึ่งเป็นไบนารี พึ่งพาแพ็กเกจ add_one ซึ่งเป็นไลบรารีของเราได้แล้ว ก่อนอื่นเราต้องเพิ่มดีเพนเดนซีแบบพาธ (path dependency) ไปยัง add_one ในไฟล์ adder/Cargo.toml
ชื่อไฟล์: adder/Cargo.toml
[dependencies]
add_one = { path = "../add_one" }
เนื่องจาก Cargo จะไม่ทึกทักเอาเองว่าเครตในเวิร์กสเปซจะพึ่งพากันเอง เราจึงต้องระบุความสัมพันธ์ของดีเพนเดนซีให้ชัดเจนเสมอ
ถัดไป มาลองเรียกใช้ฟังก์ชัน add_one (จากเครต add_one) ในเครต adder กัน ให้เปิดไฟล์ adder/src/main.rs แล้วแก้ไขฟังก์ชัน main ให้เรียกใช้ฟังก์ชัน add_one ดังที่แสดงในลิสติ้ง 14-7
fn main() {
let num = 10;
println!("Hello, world! {num} plus one is {}!", add_one::add_one(num));
}
มาลองบิลด์เวิร์กสเปซกันโดยรัน cargo build ในไดเรกทอรี add ระดับบนสุด!
$ cargo build
Compiling add_one v0.1.0 (file:///projects/add/add_one)
Compiling adder v0.1.0 (file:///projects/add/adder)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.22s
ในการรันเครตไบนารีจากไดเรกทอรี add เราสามารถระบุแพ็กเกจในเวิร์กสเปซที่ต้องการรันได้ โดยส่งอาร์กิวเมนต์ -p พร้อมกับชื่อแพ็กเกจให้กับ cargo run:
$ cargo run -p adder
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s
Running `target/debug/adder`
Hello, world! 10 plus one is 11!
คำสั่งนี้จะรันโค้ดใน adder/src/main.rs ซึ่งพึ่งพาเครต add_one
การพึ่งพาแพ็กเกจภายนอก
โปรดสังเกตว่าเวิร์กสเปซจะมีไฟล์ Cargo.lock เพียงไฟล์เดียวอยู่ที่ระดับบนสุด แทนที่จะมีไฟล์ Cargo.lock แยกในไดเรกทอรีของแต่ละเครต จุดนี้ช่วยรับประกันว่าเครตทั้งหมดจะใช้เวอร์ชันเดียวกันของทุกดีเพนเดนซี หากเราเพิ่มแพ็กเกจ rand ลงในไฟล์ adder/Cargo.toml และ add_one/Cargo.toml ทาง Cargo จะรีโซล์ฟ (resolve) ทั้งคู่ให้เป็นเวอร์ชันเดียวกันของ rand และบันทึกไว้ใน Cargo.lock เพียงไฟล์เดียว การที่เครตทุกตัวในเวิร์กสเปซใช้ดีเพนเดนซีร่วมกันเช่นนี้ทำให้มั่นใจได้ว่าเครตต่าง ๆ จะทำงานร่วมกันได้อย่างราบรื่นเสมอ มาลองเพิ่มเครต rand ลงในเซกชัน [dependencies] ของไฟล์ add_one/Cargo.toml เพื่อให้เราเรียกใช้ rand ในเครต add_one ได้:
ชื่อไฟล์: add_one/Cargo.toml
[dependencies]
rand = "0.10.1"
ตอนนี้เราสามารถเพิ่ม use rand; ลงในไฟล์ add_one/src/lib.rs ได้ และเมื่อบิลด์ทั้งเวิร์กสเปซด้วยคำสั่ง cargo build ในไดเรกทอรี add Cargo ก็จะดาวน์โหลดและคอมไพล์เครต rand เข้ามา เราจะเห็นคำเตือนหนึ่งข้อความเนื่องจากเรายังไม่ได้อ้างอิงถึง rand ที่เรานำเข้าสู่สโคป:
$ cargo build
Updating crates.io index
Downloaded rand v0.10.1
--snip--
Compiling rand v0.10.1
Compiling add_one v0.1.0 (file:///projects/add/add_one)
warning: unused import: `rand`
--> add_one/src/lib.rs:1:5
|
1 | use rand;
| ^^^^
|
= note: `#[warn(unused_imports)]` (part of `#[warn(unused)]`) on by default
warning: `add_one` (lib) generated 1 warning (run `cargo fix --lib -p add_one` to apply 1 suggestion)
Compiling adder v0.1.0 (file:///projects/add/adder)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.95s
ตอนนี้ไฟล์ Cargo.lock ระดับบนสุดจะมีข้อมูลที่ดีเพนเดนซี add_one พึ่งพา rand บันทึกไว้เรียบร้อยแล้ว อย่างไรก็ตาม แม้ว่า rand จะถูกนำมาใช้ที่จุดใดจุดหนึ่งในเวิร์กสเปซแล้ว แต่เราก็ยังไม่สามารถเรียกใช้มันในเครตอื่น ๆ ของเวิร์กสเปซได้ เว้นแต่เราจะเพิ่ม rand ลงในไฟล์ Cargo.toml ของเครตนั้น ๆ ด้วยเช่นกัน ตัวอย่างเช่น หากเราเพิ่ม use rand; ลงในไฟล์ adder/src/main.rs ของแพ็กเกจ adder เราจะพบกับข้อผิดพลาด:
$ cargo build
--snip--
Compiling adder v0.1.0 (file:///projects/add/adder)
error[E0432]: unresolved import `rand`
--> adder/src/main.rs:2:5
|
2 | use rand;
| ^^^^ no external crate `rand`
ในการแก้ไขปัญหานี้ ให้แก้ไขไฟล์ Cargo.toml ของแพ็กเกจ adder เพื่อระบุว่า rand เป็นหนึ่งในดีเพนเดนซีของมันด้วย การบิลด์แพ็กเกจ adder จะเพิ่ม rand เข้าไปในรายการดีเพนเดนซีของ adder ใน Cargo.lock โดยจะไม่มีการดาวน์โหลดชุดโค้ดของ rand ซ้ำซ้อนอีก Cargo จะคอยดูแลให้ทุกเครตในทุกแพ็กเกจของเวิร์กสเปซที่ใช้แพ็กเกจ rand ได้ใช้เวอร์ชันเดียวกัน ตราบใดที่พวกมันระบุเวอร์ชันที่เข้ากันได้ ซึ่งช่วยประหยัดพื้นที่จัดเก็บและรับประกันว่าเครตต่าง ๆ ภายในเวิร์กสเปซจะเข้ากันได้เสมอ
หากเครตต่าง ๆ ในเวิร์กสเปซระบุเวอร์ชันที่ไม่สามารถเข้ากันได้ของดีเพนเดนซีตัวเดียวกัน Cargo จะรีโซล์ฟเวอร์ชันของแต่ละตัวแยกกัน แต่ก็จะพยายามรีโซล์ฟให้มีจำนวนเวอร์ชันน้อยที่สุดเท่าที่จะเป็นไปได้
การเพิ่มเทสต์ให้เวิร์กสเปซ
เพื่อเพิ่มประสิทธิภาพและความสมบูรณ์อีกขั้น มาลองเพิ่มเทสต์สำหรับฟังก์ชัน add_one::add_one ภายในเครต add_one กัน:
ชื่อไฟล์: add_one/src/lib.rs
pub fn add_one(x: i32) -> i32 {
x + 1
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn it_works() {
assert_eq!(3, add_one(2));
}
}
คราวนี้ลองรัน cargo test ในไดเรกทอรี add ระดับบนสุด การรัน cargo test ในเวิร์กสเปซที่มีโครงสร้างเช่นนี้จะดำเนินการรันเทสต์ของทุกเครตในเวิร์กสเปซ:
$ cargo test
Compiling add_one v0.1.0 (file:///projects/add/add_one)
Compiling adder v0.1.0 (file:///projects/add/adder)
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.20s
Running unittests src/lib.rs (target/debug/deps/add_one-93c49ee75dc46543)
running 1 test
test tests::it_works ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/main.rs (target/debug/deps/adder-3a47283c568d2b6a)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Doc-tests add_one
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
เอาต์พุตส่วนแรกแสดงว่าเทสต์ it_works ในเครต add_one ผ่าน ส่วนถัดมาแสดงว่าไม่พบเทสต์ใด ๆ ในเครต adder และส่วนสุดท้ายแสดงว่าไม่พบด็อกเทสต์ (doc-test) ใด ๆ ในเครต add_one
นอกจากนี้ เรายังสามารถรันเทสต์เฉพาะเครตที่ต้องการในเวิร์กสเปซจากไดเรกทอรีระดับบนสุดได้ โดยใช้แฟล็ก -p แล้วระบุชื่อเครตที่ต้องการทดสอบ:
$ cargo test -p add_one
Finished `test` profile [unoptimized + debuginfo] target(s) in 0.00s
Running unittests src/lib.rs (target/debug/deps/add_one-93c49ee75dc46543)
running 1 test
test tests::it_works ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Doc-tests add_one
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
เอาต์พุตนี้แสดงให้เห็นว่า cargo test รันเฉพาะเทสต์ของเครต add_one เท่านั้น และไม่ได้รันเทสต์ของเครต adder
หากคุณต้องการเผยแพร่เครตในเวิร์กสเปซไปยัง crates.io แต่ละเครตในเวิร์กสเปซจะต้องถูกเผยแพร่แยกจากกัน และเช่นเดียวกับ cargo test เราสามารถเผยแพร่เฉพาะเครตใดเครตหนึ่งในเวิร์กสเปซได้โดยใช้แฟล็ก -p แล้วตามด้วยชื่อเครตที่ต้องการเผยแพร่
เพื่อเป็นการฝึกฝนเพิ่มเติม ลองเพิ่มเครต add_two เข้ามาในเวิร์กสเปซนี้ด้วยวิธีการเดียวกับเครต add_one ดูสิ!
เมื่อโปรเจกต์ของคุณเริ่มขยายใหญ่ขึ้น ลองพิจารณาใช้เวิร์กสเปซ เพราะจะช่วยให้คุณทำงานกับคอมโพเนนต์ย่อย ๆ ที่เข้าใจง่ายได้ดีกว่าการรวมเป็นโค้ดก้อนใหญ่เพียงก้อนเดียว นอกจากนี้ การรวมเครตไว้ในเวิร์กสเปซเดียวกันยังช่วยให้การประสานงานและจัดการระหว่างเครตต่าง ๆ ทำได้ง่ายขึ้น โดยเฉพาะอย่างยิ่งหากพวกมันมักจะต้องถูกแก้ไขไปพร้อม ๆ กัน