BAB 20: Module System: Module
Module Rust bisa dipindah ke berkas sendiri dengan deklarasi mod, dan letak berkas menentukan nama modul yang dipakai di dalam kode.
Isi program Rust boleh tersebar di 20 berkas, tetapi kompilator hanya membaca berkas yang dinyatakan lewat mod. Berkas .rs yang tidak pernah dideklarasikan tidak dikompilasi dan tidak menghasilkan error, sehingga kesalahan yang paling sering terjadi di tahap ini bukan error kompilasi, melainkan kode yang diam-diam tidak ikut dibangun.
Bab ini membahas cara memindahkan module ke berkas sendiri, 2 bentuk susunan folder yang dikenali Cargo, dan 3 error yang muncul saat deklarasi mod tidak cocok dengan isi folder. Setelah bab ini selesai, kamu dapat memecah program menjadi beberapa berkas modul, memilih antara bentuk gudang.rs dan gudang/mod.rs, serta membaca E0583, E0428, dan E0761 sebagai kesalahan susunan berkas. Semua contoh dijalankan dengan cargo 1.100.0 pada package toko di /tmp/latihan-rust/bab20.
Berkas terpisah butuh deklarasi mod
Module yang ditulis di berkas terpisah disebut out-of-line module. Cara memakainya 2 langkah: tulis berkasnya, lalu deklarasikan dengan mod di berkas induk. Berkas src/laporan.rs berikut berisi 1 fungsi publik dan 1 module inline di dalamnya.
pub fn judul() -> &'static str {
"laporan penjualan"
}
pub mod rinci {
pub fn baris() {
println!("{}: 3 barang", super::judul());
}
}
Berkas induk src/main.rs cukup menulis mod laporan; tanpa tanda kurung kurawal, lalu memakai isinya lewat path.
mod laporan;
fn main() {
println!("{}", laporan::judul());
laporan::rinci::baris();
}
Running `target/debug/toko`
laporan penjualan
laporan penjualan: 3 barang
Titik koma pada mod laporan; berbeda arti dari kurung kurawal. Dengan titik koma, kompilator mencari berkas src/laporan.rs atau src/laporan/mod.rs, sedangkan dengan kurung kurawal isi module ditulis langsung di tempat itu. Module rinci di dalam laporan.rs memakai super::judul() karena super dari rinci menunjuk module laporan, dan aturan path itu sama seperti yang dibahas di bab sebelumnya.
Berkas tanpa mod tidak dikompilasi
Berkas src/laporan.rs yang tetap ada di folder tetapi tidak dideklarasikan tidak akan pernah dibaca kompilator. Program tetap berhasil dibangun dan berjalan, hanya isinya berkurang. Kalau baris mod laporan; dihapus dari src/main.rs, program cukup mencetak 1 baris dari main dan tidak menyebut laporan sama sekali.
Tidak ada peringatan tentang src/laporan.rs yang terabaikan, karena Cargo memang tidak menganggap berkas itu bagian dari crate. Gejalanya mudah dikenali saat debugging: fungsi yang ditulis di berkas terpisah tidak bisa dipanggil, dan pesan errornya menyebut nama yang tidak ditemukan, bukan berkas yang hilang. Kalau itu terjadi, periksa dulu deklarasi mod di berkas induk sebelum menyalahkan isi berkas modul.
Sifat senyap itu tetap berlaku walaupun peringatan dinaikkan menjadi error. Berkas src/main.rs yang diawali #![deny(warnings)] masih berhasil dibangun dan berjalan, padahal di folder src/ ada laporan.rs, gudang.rs, dan lain/berkas.rs yang tidak pernah dideklarasikan.
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.07s
Running `target/debug/toko`
hanya main yang dikompilasi
Alasannya, daftar berkas yang dikompilasi disusun dari pohon module, bukan dari isi folder. Berkas yang tidak terjangkau deklarasi mod tidak masuk pohon itu, sehingga tidak pernah dibuka dan tidak punya kesempatan memicu peringatan apa pun.
Folder modul: gudang.rs dan gudang/stok.rs
Module yang punya anak boleh disimpan sebagai 1 berkas ditambah 1 folder dengan nama sama. Bentuk ini dipakai sejak rustc 1.30 dan menjadi cara yang dianjurkan sekarang. Susunan berkasnya seperti ini: src/main.rs, src/laporan.rs, src/gudang.rs, dan src/gudang/stok.rs.
pub mod stok;
pub fn jumlah_rak() -> i32 {
12
}
Berkas src/gudang/stok.rs berisi module anak, dan namanya tidak perlu diulang di dalam berkas.
pub fn sisa() -> i32 {
40
}
Berkas induk mendeklarasikan gudang saja, sedangkan stok dideklarasikan di dalam gudang.rs.
mod gudang;
fn main() {
println!("rak: {}", gudang::jumlah_rak());
println!("stok: {}", gudang::stok::sisa());
}
Running `target/debug/toko`
rak: 12
stok: 40
Aturan penempatan berkasnya sederhana: module anak dari gudang dicari di folder src/gudang/, dan nama berkasnya menjadi nama module. Karena itu pub mod stok; di dalam src/gudang.rs mencari src/gudang/stok.rs. Kedalaman berikutnya mengikuti pola yang sama, misalnya src/gudang/stok/detail.rs untuk module detail di dalam stok.
Dari mana module anak dicari
Rust Reference memasangkan path module dengan path berkas dalam 1 tabel, dan pasangan itu menentukan ke mana kompilator harus melihat. Akar crate dipetakan ke lib.rs atau main.rs. Module crate::util dipetakan ke util.rs. Module crate::util::config dipetakan ke util/config.rs.
Yang perlu diingat, patokan pencarian selalu folder module induk, bukan folder akar crate. Saat pub mod stok; ditulis di dalam src/gudang.rs, kompilator mencari di dalam src/gudang/, bukan di dalam src/. Karena itu menaruh stok.rs di src/ menghasilkan E0583, walaupun berkasnya ada dan isinya benar.
Konsekuensi lain, nama berkas menentukan nama module dan tidak bisa berbeda tanpa atribut #[path]. Berkas src/stok.rs selalu menjadi module bernama stok di dalam module induknya, sekalipun fungsi di dalamnya berhubungan dengan hal lain. Kalau penamaan berkas terasa janggal, yang biasanya perlu diubah adalah susunan folder, bukan nama berkasnya.
Arah sebaliknya juga berlaku: 1 folder tidak otomatis menjadi 1 module. Folder src/gudang/ hanya dibaca kalau gudang dideklarasikan sebagai module, dan berkas di dalamnya hanya dibaca kalau dideklarasikan lagi dari gudang.rs. Folder tanpa deklarasi tidak menambah apa pun ke pohon module.
Bentuk lama mod.rs dan larangan mencampurnya
Sebelum rustc 1.30, module yang punya anak disimpan sebagai folder dengan berkas mod.rs di dalamnya. Rust Reference menyebut cara itu sebagai cara lama untuk memuat module yang punya anak, lalu menyatakan bentuk baru lebih konsisten karena tidak menghasilkan banyak berkas bernama mod.rs dalam 1 proyek.
Kedua bentuk masih diterima kompilator, tetapi tidak boleh dipakai bersamaan. Reference menyatakan dengan tegas bahwa memiliki util.rs dan util/mod.rs sekaligus tidak diizinkan. Kalau keduanya ada, kompilator berhenti dengan E0761.
error[E0761]: file for module `gudang` found at both "src/gudang.rs" and "src/gudang/mod.rs"
--> src/main.rs:1:1
|
1 | mod gudang;
| ^^^^^^^^^^^
|
= help: delete or rename one of them to remove the ambiguity
For more information about this error, try `rustc --explain E0761`.
error: could not compile `toko` (bin "toko") due to 1 previous error
Pesan itu tidak memilih salah satu berkas, karena keduanya sama sahnya. Yang harus diputuskan adalah pemilik kode: hapus atau ganti nama 1 di antara keduanya. Pada package toko, berkas src/gudang/mod.rs dihapus dan bentuk src/gudang.rs dipertahankan.
Atribut path untuk letak yang tidak baku
Letak berkas module bisa dipaksa lewat atribut #[path = "..."] yang ditulis tepat di atas deklarasi mod. Atribut ini berguna saat berkas modul dikelompokkan di folder lain, misalnya src/lain/berkas.rs.
mod gudang;
#[path = "lain/berkas.rs"]
mod lain;
fn main() {
println!("rak: {}", gudang::jumlah_rak());
println!("stok: {}", gudang::stok::sisa());
lain::halo();
}
Running `target/debug/toko`
rak: 12
stok: 40
modul dengan atribut path
Jalur pada #[path] dihitung dari folder tempat berkas deklarasi berada, sehingga lain/berkas.rs berarti src/lain/berkas.rs karena deklarasinya ada di src/main.rs. Nama module tetap lain, bukan berkas, karena yang menentukan nama adalah tulisan setelah kata mod. Atribut ini sebaiknya dipakai hanya kalau susunan folder memang tidak bisa mengikuti aturan baku, karena pembaca kode jadi perlu membuka 2 tempat untuk menemukan 1 module.
Kesalahan 1: mod tanpa berkas
Kesalahan pertama muncul saat deklarasi mod ditulis lebih dulu, lalu berkasnya lupa dibuat. Berkas src/main.rs mendeklarasikan mod catatan; padahal tidak ada src/catatan.rs maupun src/catatan/mod.rs.
error[E0583]: file not found for module `catatan`
--> src/main.rs:1:1
|
1 | mod catatan;
| ^^^^^^^^^^^^
|
= help: to create the module `catatan`, create file "src/catatan.rs" or "src/catatan/mod.rs"
= note: if there is a `mod catatan` elsewhere in the crate already, import it with `use crate::...` instead
For more information about this error, try `rustc --explain E0583`.
error: could not compile `toko` (bin "toko") due to 1 previous error
Halaman resmi E0583 menjelaskan kode ini sebagai berkas yang tidak ditemukan untuk out-of-line module, dan menyarankan menyiapkan catatan.rs atau catatan/mod.rs di folder yang sama dengan berkas deklarasi. Perbaikan pada kasus ini 2 pilihan: buat berkasnya, atau hapus deklarasi mod catatan; kalau module itu memang tidak dipakai.
Kesalahan 2: mod dideklarasikan 2 kali
Kesalahan kedua muncul saat deklarasi tidak sengaja ditulis berulang, misalnya setelah menyalin potongan kode dari berkas lain. Berkas src/main.rs memuat 2 baris mod laporan;.
error[E0428]: the name `laporan` is defined multiple times
--> src/main.rs:2:1
|
1 | mod laporan;
| ------------ previous definition of the module `laporan` here
2 | mod laporan;
| ^^^^^^^^^^^^ `laporan` redefined here
|
= note: `laporan` must be defined only once in the type namespace of this module
For more information about this error, try `rustc --explain E0428`.
error: could not compile `toko` (bin "toko") due to 1 previous error
Kompilator menunjuk kedua baris, sehingga asal duplikatnya langsung terlihat. Nama module hidup di namespace tipe bersama struct, enum, dan trait, dan 1 nama hanya boleh dideklarasikan 1 kali per module induk. Perbaikannya menghapus 1 dari 2 baris itu, bukan mengganti nama salah satunya, karena keduanya menunjuk berkas yang sama.
Latihan
- Pindahkan 1 fungsi dari
src/main.rskesrc/alat.rs, deklarasikan denganmod alat;, lalu panggil. - Tambahkan module anak
src/alat/teks.rs, deklarasikan darialat.rs, dan panggil fungsinya lewat path 2 tingkat. - Hapus deklarasi
modpada latihan 1, jalankan program, dan catat apa yang terjadi. - Ubah bentuk
src/alat.rsmenjadisrc/alat/mod.rstanpa menghapus berkas lama, lalu baca error yang muncul dan perbaiki. - Pindahkan 1 module ke folder
src/lain/memakai atribut#[path], lalu jalankan.
Ringkasan
Module di berkas terpisah dipakai lewat deklarasi mod nama; tanpa kurung kurawal, dan berkas yang tidak dideklarasikan tidak ikut dikompilasi tanpa peringatan apa pun. Module yang punya anak memakai bentuk nama.rs ditambah folder nama/, atau bentuk lama nama/mod.rs, dan keduanya tidak boleh dipakai bersamaan karena memicu E0761. Deklarasi tanpa berkas menghasilkan E0583, deklarasi ganda menghasilkan E0428, dan atribut #[path] hanya dipakai saat letak berkas memang menyimpang dari aturan baku.
Referensi
- The Rust Programming Language. Control Scope and Privacy with Modules.
- The Rust Reference. Modules.
- rustc. Error code E0583.
- rustc. Error code E0761.