BAB 19: Module System: Package & Crate
Package adalah folder berisi Cargo.toml, crate adalah unit yang dikompilasi rustc, dan 1 package bisa menghasilkan beberapa crate sekaligus.
Perintah cargo build tidak mengompilasi package. Yang dikompilasi adalah crate di dalam package, dan 1 folder package boleh berisi lebih dari 1 crate. Karena itu 1 package bisa menghasilkan beberapa berkas hasil build sekaligus: 2 biner dan 1 library, misalnya.
Bab ini membahas 3 tingkatan yang sering tertukar, yaitu package, crate, dan module, lalu cara memilih bentuk crate saat membuat proyek. Setelah bab ini selesai, kamu dapat membuat package dengan cargo new, menambah binary crate kedua di src/bin, memakai library crate dari binary di package yang sama, dan menjelaskan mengapa tanda hubung pada nama package berubah menjadi garis bawah di dalam kode. Semua perintah dijalankan dengan cargo 1.100.0 di folder /tmp/latihan-rust/bab19.
Package: 1 folder yang punya Cargo.toml
Package adalah kumpulan 1 crate atau lebih yang disertai berkas Cargo.toml. Buku resmi Rust menyebut package sebagai bundle of one or more crates yang menyediakan satu set fungsi, dan Cargo.toml menjelaskan cara membangun crate di dalamnya. Tanpa Cargo.toml, sebuah folder hanyalah folder biasa yang tidak dikenal Cargo.
Perintah cargo new paket_nilai --vcs none membuat package sekaligus mengisi berkas minimumnya, dan mencetak 2 baris berikut.
Creating binary (application) `paket_nilai` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
Opsi --vcs none mencegah Cargo membuat repositori git sendiri di dalam folder. Hasil perintah itu 2 berkas saja, yaitu Cargo.toml di akar folder dan src/main.rs sebagai crate root. Berkas Cargo.toml yang dihasilkan berisi 4 kunci, dan hanya itu yang dibutuhkan agar package bisa dibangun.
[package]
name = "paket_nilai"
version = "0.1.0"
edition = "2024"
[dependencies]
Nilai edition = "2024" diisi otomatis oleh cargo 1.100.0, dan version dimulai dari 0.1.0. Bagian [dependencies] masih kosong karena crate ini belum memakai crate lain. Menambah crate lain berarti menulis namanya di bagian itu, dan cargo add mengisi baris tersebut tanpa perlu menghitung versi sendiri.
Varian library dibuat dengan menambah opsi --lib pada perintah yang sama, dan Cargo mengganti kata binary (application) menjadi library pada keluarannya. Isi foldernya juga berbeda: src/main.rs diganti src/lib.rs, dan crate itu tidak punya fungsi main.
Crate: hasil kompilasi yang dijalankan atau dipakai
Crate adalah unit terkecil yang dilihat kompilator Rust. Buku resmi Rust menulis bahwa crate adalah jumlah kode terkecil yang dipertimbangkan kompilator pada satu waktu, dan Reference menyebut tiap kompilasi memproses 1 crate dalam bentuk sumber lalu menghasilkan 1 crate dalam bentuk biner, berupa executable atau library.
Crate datang dalam 2 bentuk. Binary crate adalah program yang bisa dijalankan dan wajib punya fungsi main. Library crate tidak punya main dan tidak menghasilkan executable, sehingga hanya bisa dipakai crate lain. Package yang dibuat perintah di atas menghasilkan binary crate, karena isinya src/main.rs.
Ukuran hasil build memperlihatkan perbedaan bentuk itu. Biner hasil build paket_nilai berukuran 4.501.120 byte, sedangkan library crate paket-hitung hanya 7.090 byte karena tidak membawa kode startup program. Keduanya sama-sama hasil kompilasi 1 crate, hanya bentuk keluarannya yang berbeda.
3 nama yang harus dibedakan
Satu package membawa 3 nama yang mirip tetapi dipakai di tempat berbeda. Nama package ditulis di Cargo.toml dan boleh memakai tanda hubung. Nama crate diturunkan dari nama package dengan tanda hubung diubah menjadi garis bawah, dan nama inilah yang dipakai di dalam kode. Nama module adalah bagian path yang dibahas di bab sebelumnya, misalnya crate:: untuk akar crate.
Aturan penggantian tanda hubung bukan pilihan gaya. Karakter - adalah operator pengurangan di Rust, sehingga paket-hitung::luas(3, 4) dibaca kompilator sebagai pengurangan antara nama paket dan nama hitung. Bagian tentang kesalahan tanda hubung di bawah menunjukkan akibatnya.
Menambah binary crate kedua di src/bin
Package boleh berisi beberapa binary crate. Cargo membaca semua berkas .rs di dalam src/bin/ sebagai binary crate tersendiri, dan nama berkasnya menjadi nama biner. Berkas src/bin/ringkas.rs berikut menambah biner kedua pada paket_nilai.
fn main() {
println!("ini biner ringkas");
}
Setelah berkas itu ada, package berisi 2 binary crate. Perintah cargo run tanpa pilihan target berhenti dengan error, karena Cargo tidak punya alasan memilih salah satu.
error: `cargo run` could not determine which binary to run. Use the `--bin` option to specify a binary, or the `default-run` manifest key.
available binaries: paket_nilai, ringkas
Kata error itu datang dari Cargo, bukan dari rustc, sehingga tidak ada kode E yang menyertainya. Ada 2 perbaikan yang sama sahnya: menyebut target setiap kali menjalankan dengan --bin, atau menulis default-run = "paket_nilai" di bagian [package] pada Cargo.toml. Perbaikan pertama tidak mengubah berkas apa pun.
cargo run --bin ringkas
Running `target/debug/ringkas`
ini biner ringkas
Kedua biner dibangun terpisah walaupun berada di 1 package, dan masing-masing punya fungsi main sendiri. Ukurannya 4.501.120 byte untuk paket_nilai dan 4.501.096 byte untuk ringkas, selisih 24 byte karena keduanya crate yang berbeda.
Package yang berisi library dan binary
Bentuk lain yang sering dipakai adalah 1 package berisi library crate dan binary crate sekaligus. Package paket-hitung dibuat dengan cargo new --lib, lalu isi src/lib.rs diganti menjadi 1 fungsi publik.
pub fn luas(p: i32, l: i32) -> i32 {
p * l
}
Binary crate di src/bin/pakai.rs memakai fungsi itu lewat nama crate, bukan lewat nama package.
fn main() {
println!("{}", paket_hitung::luas(3, 4));
}
cargo run --bin pakai
Running `target/debug/pakai`
12
Dokumentasi Cargo menyatakan biner boleh memakai public API dari library package-nya. Mekanismenya sederhana: Cargo melihat ada src/lib.rs, membangunnya sebagai library crate, lalu menautkannya ke setiap binary crate di package yang sama. Karena library itu tidak punya main, ia tidak bisa dijalankan sendiri dan hanya berguna sebagai kumpulan fungsi, struct, atau trait.
Kesalahan: tanda hubung dipakai di dalam kode
Kesalahan ini muncul saat nama package disalin apa adanya ke dalam kode. Berkas src/bin/salah.rs memakai paket-hitung::luas(3, 4) padahal crate-nya bernama paket_hitung.
fn main() {
println!("{}", paket-hitung::luas(3, 4));
}
error[E0425]: cannot find value `paket` in this scope
--> src/bin/salah.rs:2:20
|
2 | println!("{}", paket-hitung::luas(3, 4));
| ^^^^^ not found in this scope
error[E0433]: cannot find module or crate `hitung` in this scope
--> src/bin/salah.rs:2:26
|
2 | println!("{}", paket-hitung::luas(3, 4));
| ^^^^^^ use of unresolved module or unlinked crate `hitung`
|
= help: if you wanted to use a crate named `hitung`, use `cargo add hitung` to add it to your `Cargo.toml`
Some errors have detailed explanations: E0425, E0433.
For more information about an error, try `rustc --explain E0425`.
error: could not compile `paket-hitung` (bin "salah") due to 2 previous errors
Kompilator melaporkan 2 error untuk 1 baris karena tanda hubung dibaca sebagai operator. Sisi kiri paket dianggap nilai yang tidak ada di scope, sisi kanan hitung dianggap crate yang tidak dikenal. Perbaikannya 1 karakter per kemunculan: tulis paket_hitung::luas(3, 4), dan kedua error itu hilang seluruhnya. Saran cargo add hitung pada keluaran di atas menyesatkan untuk kasus ini, karena yang salah bukan dependensi yang belum ditambah.
Membaca hasil build di folder target
Semua hasil build ditulis ke folder target/. Isi folder itu menjelaskan perbedaan package dengan crate lebih baik daripada penjelasan mana pun, karena di sanalah terlihat berapa crate yang dihasilkan. Berikut isi target/debug pada package paket-hitung setelah 1 library dan 1 biner dibangun.
build
examples
incremental
libpaket_hitung.d
libpaket_hitung.rlib
pakai
pakai.d
Berkas libpaket_hitung.rlib adalah library crate, sedangkan pakai adalah binary crate. Berkas berakhiran .d menyimpan daftar berkas sumber yang dipakai saat build, sehingga Cargo tahu apa yang perlu dibangun ulang ketika 1 berkas berubah. Folder incremental/ menyimpan potongan hasil kompilasi sebelumnya, dan build/ dipakai crate yang punya skrip build.
Satu hal terakhir yang berguna saat membaca struktur package: nama folder tidak menentukan nama crate. Kalau folder diganti nama, crate tetap bernama sesuai name di Cargo.toml, dan pesan error tetap memakai nama itu. Yang berubah hanya jalur tempat Cargo mencari Cargo.toml saat perintah dijalankan.
Latihan
- Buat package
latihan_paketdengancargo new --vcs none, lalu jalankan dan catat keluaran bawaannya. - Tambahkan
src/bin/kedua.rsyang mencetak 1 baris, lalu jalankan keduanya dengan--bin. - Ubah package menjadi berisi library dengan
src/lib.rs, pindahkan 1 fungsi ke sana, dan panggil darisrc/main.rs. - Buat package bernama
latihan-paket, lalu tulis pemanggilan yang salah dengan tanda hubung, catat kode error yang muncul, dan perbaiki. - Bandingkan ukuran biner dan berkas
.rlibhasil build, lalu jelaskan mengapa keduanya berbeda jauh.
Ringkasan
Package adalah folder yang punya Cargo.toml dan berisi 1 crate atau lebih, sedangkan crate adalah unit yang dikompilasi rustc menjadi executable atau library. Binary crate wajib punya main, library crate tidak punya main dan dipakai lewat nama crate-nya dari crate lain di package yang sama. Nama package boleh memakai tanda hubung, tetapi di dalam kode nama itu harus ditulis dengan garis bawah, dan package berisi 2 biner menuntut pilihan --bin atau kunci default-run.
Referensi
- The Rust Programming Language. Packages and Crates.
- The Rust Reference. Crates and source files.
- The Cargo Book. Cargo Targets.
- The Cargo Book. The Manifest Format.