Module System

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.

RSRUST
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.

RSRUST
mod laporan;

fn main() {
    println!("{}", laporan::judul());
    laporan::rinci::baris();
}
CodeTEXT
     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.

CodeTEXT
     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.

RSRUST
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.

RSRUST
pub fn sisa() -> i32 {
    40
}

Berkas induk mendeklarasikan gudang saja, sedangkan stok dideklarasikan di dalam gudang.rs.

RSRUST
mod gudang;

fn main() {
    println!("rak: {}", gudang::jumlah_rak());
    println!("stok: {}", gudang::stok::sisa());
}
CodeTEXT
     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.

CodeTEXT
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.

RSRUST
mod gudang;
#[path = "lain/berkas.rs"]
mod lain;

fn main() {
    println!("rak: {}", gudang::jumlah_rak());
    println!("stok: {}", gudang::stok::sisa());
    lain::halo();
}
CodeTEXT
     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.

CodeTEXT
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;.

CodeTEXT
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

  1. Pindahkan 1 fungsi dari src/main.rs ke src/alat.rs, deklarasikan dengan mod alat;, lalu panggil.
  2. Tambahkan module anak src/alat/teks.rs, deklarasikan dari alat.rs, dan panggil fungsinya lewat path 2 tingkat.
  3. Hapus deklarasi mod pada latihan 1, jalankan program, dan catat apa yang terjadi.
  4. Ubah bentuk src/alat.rs menjadi src/alat/mod.rs tanpa menghapus berkas lama, lalu baca error yang muncul dan perbaiki.
  5. 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

  1. The Rust Programming Language. Control Scope and Privacy with Modules.
  2. The Rust Reference. Modules.
  3. rustc. Error code E0583.
  4. rustc. Error code E0761.