Perintah Cargo Bermanfaat

Kita sudah lulus dari dasar cargo: membuat package, mengatur dependency, dan membangun dua profil. Tetapi pekerjaan sehari-hari menghadirkan pertanyaan-pertanyaan lanjutan: dependency rand ini sebenarnya menyeret crate apa saja? Versi mana yang terpasang sekarang, dan apakah masih yang terbaru? Bagaimana caranya menumbuhkan dokumentasi API milik proyek sendiri? Cargo menyediakan tiga perintah inti untuk menjawab semuanya — cargo tree, cargo update, dan cargo doc — dan semuanya sudah terpasang bersama toolchain tanpa konfigurasi tambahan. Chapter ini menjalankan ketiganya pada proyek undian-acak yang kita bangun sejak Chapter Dependensi, lalu merangkainya menjadi alur kerja yang wajar dipakai setiap hari.

cargo tree: Memetakan Seluruh Dependensi #

Masalah klasik proyek ber-dependensi: manifest hanya menampilkan satu tingkat — kita menulis rand, tetapi rand sendiri membawa crate lain yang membawa crate lain lagi. Perintah cargo tree menggambar pohon lengkap dari resolusi Cargo.lock:

cargo tree

Output yang Dihasilkan:

undian-acak v0.1.0 (/tmp/w5a/undian-acak)
└── rand v0.10.3
    ├── chacha20 v0.10.2
    │   ├── cfg-if v1.0.5
    │   ├── cpufeatures v0.3.1
    │   └── rand_core v0.10.1
    ├── getrandom v0.4.3
    │   ├── cfg-if v1.0.5
    │   ├── libc v0.2.190
    │   └── rand_core v0.10.1
    └── rand_core v0.10.1

Cara membacanya: setiap baris adalah satu package dengan versi pasti hasil kunci, dan indentasi menyatakan relasi pemakai-ke-penyedia — rand memakai chacha20, getrandom, dan rand_core; getrandom memakai libc untuk berbicara dengan sistem operasi. Satu crate bisa muncul di beberapa cabang (cfg-if, rand_core) karena dipakai lebih dari satu dependency, tetapi tetap dikompilasi sekali berkat kunci versi yang sama.

Struktur pohon tersebut bisa dibaca baris per baris:

1. Baris 1 (undian-acak v0.1.0 (/tmp/w5a/undian-acak)): akar pohon selalu package kita sendiri — satu-satunya tanpa versi dari registry.
2. Baris 2 (└── rand v0.10.3): dependency langsung dari manifest, dengan versi pasti hasil resolusi.
3. Baris 3 ( ├── chacha20 v0.10.2): dependency kedua tingkat — tidak kita minta, tetapi rand memintanya; chacha20 adalah generator berbasis enkripsi yang dipakai rand.
4. Baris 7 ( ├── getrandom v0.4.3): jembatan rand ke sumber acak sistem operasi; cabang libc di bawahnya hanya relevan di Linux.
5. Baris 11 ( └── rand_core v0.10.1): inti trait dan tipe dasar rand — tanda └── menandai anak terakhir dari rand.

Kebalikan pertanyaannya juga penting: bukan “rand menyeret apa”, melainkan “siapa yang memakai rand”. Opsi -i membalik arah pohon:

cargo tree -i rand

Output yang Dihasilkan:

rand v0.10.3
└── undian-acak v0.1.0 (/tmp/w5a/undian-acak)

Pohon terbalik ini menyala di proyek besar: bila galat kompilasi menyebut crate asing, cargo tree -i <crate> langsung menunjukkan jalur dependency mana yang menghadirkan crate tersebut ke proyek kita. Opsi -e features — yang sudah kita pakai pada Chapter Fitur Features — melengkapi keluarga ini dengan memperlihatkan keadaan fitur tiap crate, dan kombinasi -i rand -e features menjawab pertanyaan paling misterius: “fitur rand mana saja yang aktif, dan siapa pemintanya”.

Proyek nyata juga memakai cargo tree --duplicate untuk mencari crate yang terpasang di dua versi berbeda — kondisi yang menaikkan ukuran binary dan memperpanjang waktu build. Perintah cargo tree membaca Cargo.lock tanpa menyentuh jaringan, sehingga aman dijalankan kapan pun, bahkan saat offline.

cargo update: Menyegarkan Versi Terkunci #

Chapter Versi dan SemVer menegaskan pembagian kerja: manifest menyimpan rentang, Cargo.lock menyimpan keputusan. Perintah cargo update mengulang keputusan itu — setiap dependency dinaikkan ke versi terbaru yang masih berada di dalam rentang. Agar perubahannya kelihatan, kita longgarkan requirement rand di manifest menjadi rand = "0.10", lalu turunkan sengaja versi terkunci dari 0.10.3:

cargo update -p rand --precise 0.10.2

Output yang Dihasilkan:

    Updating crates.io index
 Downgrading rand v0.10.3 -> v0.10.2

Opsi -p rand membatasi aksi pada crate tersebut saja, dan --precise 0.10.2 menjatuhkan pilihan persis ke 0.10.2. Sekarang naikkan kembali ke versi tertinggi dalam rentang:

cargo update

Output yang Dihasilkan:

    Updating crates.io index
     Locking 1 package to highest Rust 1.99.0 compatible versions
    Updating rand v0.10.2 -> v0.10.3

Perintah cargo update tanpa argumen menaikkan rand kembali ke 0.10.3 — versi tertinggi yang diizinkan rentang "0.10". Pesan Locking 1 package menghitung banyaknya entri Cargo.lock yang berubah akibat resolusi ulang tersebut.

Dua waktunya memakai cargo update: berkala, untuk mengambil perbaikan galat dan celah keamanan pada dependency tanpa mengubah manifest; dan sesaat setelah menaikkan versi requirement di manifest, agar resolusi langsung menyegarkan. Perintah ini menulis perubahan ke Cargo.lock — perubahan itulah yang dibaca rekan tim lewat version control.

cargo doc: Menumbuhkan Dokumentasi #

Ketiga perintah inti kita berurusan dengan kode yang sudah ada; cargo doc berurusan dengan penjelasannya. Rust memiliki format dokumentasi bawaan: komentar /// di atas item menjadi halaman dokumentasi, dan rustc merender seluruhnya menjadi situs HTML statis dengan pencarian dan navigasi. Perintahnya:

cargo doc --no-deps

Output yang Dihasilkan:

 Documenting undian-acak v0.1.0 (/tmp/w5a/undian-acak)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.10s
   Generated /tmp/w5a/undian-acak/target/doc/undian_acak/index.html

Opsi --no-deps membatasi dokumentasi pada package kita saja — tanpa opsi tersebut, cargo juga merender dokumentasi seluruh dependency, proses yang bisa memakan waktu pada proyek besar. Situs hasilnya mendarat di target/doc/:

target/doc/
├── crates.js
├── help.html
├── search.index
├── settings.html
├── static.files/
├── src/
└── undian_acak/
    ├── all.html
    ├── fn.main.html
    ├── index.html
    └── sidebar-items.js

Halaman undian_acak/index.html adalah pintu masuknya — cukup dibuka di browser, atau dijinkan cargo membukakan lewat cargo doc --no-deps --open. Berkas search.index menopang fitur pencarian di situs tersebut; karena proyek kita belum punya komentar ///, dokumentasinya masih sebatas daftar fungsi main. Format dokumentasi lengkap — ///, contoh kode yang ikut teruji, sampai penanda # Panics — dibahas tuntas pada Section Dokumentasi.

Satu perbedaan penting dari perintah lain: cargo doc menjalankan rustdoc, perkakas saudara rustc yang mengambil komentar dokumentasi beserta kode contohnya, memeriksa bahwa contoh memang valid, lalu merender HTML. Artinya dokumentasi yang jelek — contoh yang tak bisa dikompilasi — terdeteksi lebih awal tanpa menunggu pemakai komplain.

Merangkai Alur Kerja #

Perintah-perintah ini paling bernilai ketika dipakai pada momen yang tepat. Pola harian yang sehat di proyek ber-dependensi:

Urutan cargo update diikuti cargo test sengaja berdampingan: versi dependency yang naik dapat mengubah perilaku — meski SemVer menjanjikan kompatibilitas, keputusan akhir tetap milik test kita. Perubahan Cargo.lock yang lolos test barulah layak dibagikan ke rekan tim.

Ringkasan #

Tiga perintah menuntaskan perkakas pengelolaan sehari-hari: cargo tree memetakan pohon dependency dari Cargo.lock beserta versi terpasang dan bisa dibalik dengan -i untuk melacak asal crate; cargo update menaikkan versi terkunci ke versi tertinggi dalam rentang manifest, dengan --precise untuk memilih versi eksplisit; dan cargo doc --no-deps menumbuhkan situs dokumentasi HTML di target/doc/ dari komentar ///. Dokumentasi yang rapi dan dependency yang sehat adalah dua bekal utama crate yang dibagikan ke publik — dan publikasi itulah langkah pamungkas Section ini pada Chapter berikutnya.