Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

เวิร์กสเปซของ 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 ดูสิ!

เมื่อโปรเจกต์ของคุณเริ่มขยายใหญ่ขึ้น ลองพิจารณาใช้เวิร์กสเปซ เพราะจะช่วยให้คุณทำงานกับคอมโพเนนต์ย่อย ๆ ที่เข้าใจง่ายได้ดีกว่าการรวมเป็นโค้ดก้อนใหญ่เพียงก้อนเดียว นอกจากนี้ การรวมเครตไว้ในเวิร์กสเปซเดียวกันยังช่วยให้การประสานงานและจัดการระหว่างเครตต่าง ๆ ทำได้ง่ายขึ้น โดยเฉพาะอย่างยิ่งหากพวกมันมักจะต้องถูกแก้ไขไปพร้อม ๆ กัน