Cargo Workspaces
Di Bab 12, kita membangun sebuah package yang berisi sebuah binary crate dan sebuah library crate. Seiring proyekmu berkembang, mungkin kamu mendapati library crate terus membesar dan ingin memecah package lebih lanjut menjadi beberapa library crate. Cargo menyediakan fitur bernama workspaces yang bisa membantu mengelola beberapa package terkait yang dikembangkan secara bersamaan.
Membuat Workspace
Sebuah workspace adalah kumpulan package yang berbagi Cargo.lock dan direktori output yang sama. Mari kita buat sebuah proyek memakai workspace—kita akan memakai kode yang sederhana agar bisa fokus pada struktur workspacenya. Ada beberapa cara menyusun workspace, jadi kita akan menunjukkan satu cara yang umum. Kita akan membuat workspace yang berisi satu binary dan dua library. Binary yang menyediakan fungsi utama akan bergantung pada kedua library itu. Satu library menyediakan fungsi add_one dan library lainnya fungsi add_two. Ketiga crate ini akan menjadi bagian dari workspace yang sama. Kita mulai dengan membuat direktori baru untuk workspace:
$ mkdir add
$ cd add
Berikutnya, di direktori add, kita membuat file Cargo.toml yang akan mengonfigurasi seluruh workspace. File ini tidak akan punya bagian [package]. Sebaliknya, file ini dimulai dengan bagian [workspace] yang memungkinkan kita menambahkan anggota ke dalam workspace. Kita juga memastikan memakai versi terbaru dan terbaik dari algoritma resolver Cargo di workspace dengan menetapkan nilai resolver menjadi "3":
Nama file: Cargo.toml
[workspace]
resolver = "3"
Berikutnya, kita akan membuat binary crate adder dengan menjalankan cargo new di dalam direktori add:
$ cargo new adder
Created binary (application) `adder` package
Adding `adder` as member of workspace at `file:///projects/add`
Menjalankan cargo new di dalam workspace juga otomatis menambahkan package yang baru dibuat ke kunci members dalam definisi [workspace] di Cargo.toml workspace, seperti ini:
[workspace]
resolver = "3"
members = ["adder"]
Pada titik ini, kita bisa build workspace dengan menjalankan cargo build. File-file di direktori add milikmu seharusnya terlihat seperti ini:
├── Cargo.lock
├── Cargo.toml
├── adder
│ ├── Cargo.toml
│ └── src
│ └── main.rs
└── target
Workspace punya satu direktori target di level teratas tempat hasil kompilasi ditempatkan; package adder tidak punya direktori target-nya sendiri. Bahkan jika kita menjalankan cargo build dari dalam direktori adder, hasil kompilasinya tetap akan berakhir di add/target, bukan add/adder/target. Cargo menyusun direktori target di dalam workspace seperti ini karena crate-crate dalam workspace memang dirancang untuk saling bergantung. Jika setiap crate punya direktori target-nya sendiri, masing-masing crate harus mengompilasi ulang setiap crate lain di workspace untuk menaruh hasil kompilasinya di direktori target-nya sendiri. Dengan berbagi satu direktori target, para crate bisa menghindari build ulang yang tidak perlu.
Membuat Package Kedua di dalam Workspace
Berikutnya, mari kita buat package anggota lain di workspace dan menamainya add_one. Hasilkan sebuah library crate baru bernama 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 di level teratas sekarang akan menyertakan path add_one dalam daftar members:
Nama file: Cargo.toml
[workspace]
resolver = "3"
members = ["adder", "add_one"]
Direktori add milikmu sekarang seharusnya punya direktori dan file-file ini:
├── Cargo.lock
├── Cargo.toml
├── add_one
│ ├── Cargo.toml
│ └── src
│ └── lib.rs
├── adder
│ ├── Cargo.toml
│ └── src
│ └── main.rs
└── target
Di file add_one/src/lib.rs, mari kita tambahkan fungsi add_one:
Nama file: add_one/src/lib.rs
pub fn add_one(x: i32) -> i32 {
x + 1
}
Sekarang kita bisa membuat package adder yang berisi binary bergantung pada package add_one yang berisi library kita. Pertama, kita perlu menambahkan dependensi path pada add_one ke adder/Cargo.toml.
Nama file: adder/Cargo.toml
[dependencies]
add_one = { path = "../add_one" }
Cargo tidak mengasumsikan bahwa crate-crate dalam workspace akan saling bergantung, jadi kita perlu menyatakan hubungan dependensinya secara eksplisit.
Berikutnya, mari kita pakai fungsi add_one (dari crate add_one) di dalam crate adder. Buka file adder/src/main.rs dan ubah fungsi main agar memanggil fungsi add_one, seperti pada Listing 14-7.
fn main() {
let num = 10;
println!("Hello, world! {num} plus one is {}!", add_one::add_one(num));
}
add_one dari crate adderMari build workspace dengan menjalankan cargo build di direktori add level teratas!
$ 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
Untuk menjalankan binary crate dari direktori add, kita bisa menentukan package mana di workspace yang ingin dijalankan dengan memakai argumen -p dan nama package bersama 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!
Ini menjalankan kode di adder/src/main.rs, yang bergantung pada crate add_one.
Bergantung pada Package Eksternal
Perhatikan bahwa workspace hanya punya satu file Cargo.lock di level teratas, bukan sebuah Cargo.lock di direktori masing-masing crate. Ini memastikan semua crate memakai versi yang sama dari semua dependensi. Jika kita menambahkan package rand ke file adder/Cargo.toml dan add_one/Cargo.toml, Cargo akan menyelesaikan keduanya menjadi satu versi rand dan mencatatnya di Cargo.lock yang satu itu. Dengan membuat semua crate di workspace memakai dependensi yang sama, para crate akan selalu kompatibel satu sama lain. Mari tambahkan crate rand ke bagian [dependencies] di file add_one/Cargo.toml agar kita bisa memakai crate rand di dalam crate add_one:
Nama file: add_one/Cargo.toml
[dependencies]
rand = "0.10.1"
Sekarang kita bisa menambahkan use rand; ke file add_one/src/lib.rs, dan build seluruh workspace dengan menjalankan cargo build di direktori add akan mengambil dan mengompilasi crate rand. Kita akan mendapat satu warning karena kita tidak merujuk ke rand yang sudah kita bawa ke scope:
$ 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 di level teratas sekarang berisi informasi tentang dependensi add_one pada rand. Namun, meskipun rand dipakai di suatu tempat di workspace, kita tidak bisa memakainya di crate lain dalam workspace kecuali kita menambahkan rand ke file Cargo.toml mereka juga. Misalnya, jika kita menambahkan use rand; ke file adder/src/main.rs untuk package adder, kita akan mendapat error:
$ 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`
Untuk memperbaikinya, edit file Cargo.toml untuk package adder dan nyatakan bahwa rand juga merupakan dependensinya. Build package adder akan menambahkan rand ke daftar dependensi untuk adder di Cargo.lock, tetapi tidak ada salinan tambahan rand yang akan diunduh. Cargo akan memastikan setiap crate di setiap package dalam workspace yang memakai package rand memakai versi yang sama selama mereka menentukan versi rand yang kompatibel, sehingga menghemat ruang dan memastikan crate-crate di workspace kompatibel satu sama lain.
Jika crate-crate di workspace menentukan versi yang tidak kompatibel dari dependensi yang sama, Cargo akan menyelesaikan masing-masing, tetapi tetap berusaha menyelesaikan sesedikit mungkin versi.
Menambahkan Test ke dalam Workspace
Sebagai penyempurnaan lain, mari kita tambahkan test untuk fungsi add_one::add_one di dalam crate add_one:
Nama file: 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));
}
}
Sekarang jalankan cargo test di direktori add level teratas. Menjalankan cargo test di workspace yang disusun seperti ini akan menjalankan test untuk semua crate di workspace:
$ 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
Bagian pertama dari output menunjukkan bahwa test it_works di crate add_one lulus. Bagian berikutnya menunjukkan bahwa tidak ada test yang ditemukan di crate adder, lalu bagian terakhir menunjukkan bahwa tidak ada documentation test yang ditemukan di crate add_one.
Kita juga bisa menjalankan test untuk satu crate tertentu di workspace dari direktori level teratas dengan memakai flag -p dan menentukan nama crate yang ingin kita test:
$ 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
Output ini menunjukkan cargo test hanya menjalankan test untuk crate add_one dan tidak menjalankan test crate adder.
Jika kamu mempublikasikan crate-crate di workspace ke crates.io, setiap crate di workspace perlu dipublikasikan secara terpisah. Seperti cargo test, kita bisa mempublikasikan satu crate tertentu di workspace dengan memakai flag -p dan menentukan nama crate yang ingin kita publikasikan.
Untuk latihan tambahan, tambahkan crate add_two ke workspace ini dengan cara yang mirip dengan crate add_one!
Seiring proyekmu bertumbuh, pertimbangkan untuk memakai workspace: ini memungkinkan kamu bekerja dengan komponen-komponen yang lebih kecil dan lebih mudah dipahami daripada satu gumpalan kode besar. Selain itu, menyimpan crate-crate dalam workspace bisa membuat koordinasi antarcrate lebih mudah jika mereka sering diubah bersamaan.