Package dan Cargo.toml

Setiap perintah cargo yang kita jalankan — build, run, test, sampai doc — selalu dimulai dari kebiasaan yang sama: membaca satu berkas bernama Cargo.toml di akar proyek. Berkas ini adalah manifest, kartu identitas sekaligus kontrak antara kita dan cargo: nama apa yang dipakai, versi berapa yang sedang dibangun, edition bahasa mana yang aktif, dan dependency apa saja yang boleh diunduh. Pada Chapter Memulai dengan Cargo kita sudah membaca manifest bawaan sekilas; Chapter ini membedahnya sampai ke konsekuensi tiap kunci, menambahkan metadata yang dibutuhkan saat package dibagikan ke publik, dan membuktikan bahwa setiap nilai di manifest benar-benar terbaca oleh cargo — termasuk saat nilainya salah.

Manifest: Kontrak yang Dibaca Berulang Kali #

Cargo tidak menyimpan konfigurasi proyek di registry tersembunyi atau berkas biner — semua keputusan administratif hidup di Cargo.toml berformat TOML yang bisa kita baca dan sunting dengan editor teks. Format TOML menyusun data dalam tabel yang dibuka dengan header berkurung siku, misalnya [package], lalu diisi pasangan kunci = "nilai".

Struktur manifest minimal memuat dua tabel: [package] untuk identitas package dan [dependencies] untuk daftar crate eksternal. Perintah cargo new menuliskan keduanya otomatis, termasuk saat kita membuat library:

cargo new sapa --lib

Output yang Dihasilkan:

    Creating library `sapa` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

Kata library pada baris pertama menandakan package yang dihasilkan: cargo membuat src/lib.rs sebagai crate root, bukan src/main.rs. Note pada baris kedua mengarahkan kita ke dokumentasi resmi berisi daftar kunci manifest lengkap — cargo sendiri mengakui bahwa manifest bisa jauh lebih kaya dari yang ditulisnya.

Bedah Manifest Bawaan #

Isi Cargo.toml yang ditulis cargo untuk package sapa:

[package]
name = "sapa"
version = "0.1.0"
edition = "2024"

[dependencies]

Mari kita bedah makna dan konsekuensi setiap barisnya:

1. Baris 1 ([package]): membuka tabel metadata. Semua kunci di bawah header ini sampai header tabel berikutnya milik identitas package.
2. Baris 2 (name = "sapa"): nama package. Nama menjadi dasar nama crate (sapa) dan nama artifak; untuk nama yang memakai tanda hubung seperti kasir-warung, crate-nya bernama kasir_warung dengan underscore. Nama juga menjadi alamat package di crates.io, sehingga sebaiknya ditulis dalam format kebab-case sejak awal.
3. Baris 3 (version = "0.1.0"): nomor versi package mengikuti pola SemVer MAJOR.MINOR.PATCH. Angka ini tercetak pada setiap laporan build, dan nantinya menjadi identitas rilis ketika package dipublikasikan.
4. Baris 4 (edition = "2024"): edition bahasa yang aktif untuk kode di package ini. Edition menentukan aturan bahasa mana yang berlaku — berbeda dari versi toolchain yang terpasang di komputer.
5. Baris 6 ([dependencies]): tabel daftar dependency, masih kosong. Kehadiran header yang kosong tetap sah; kita tinggal menambahkan baris dependency di bawahnya saat dibutuhkan.

Versi Package Muncul di Setiap Build #

Nilai version bukan hiasan — cargo mencantumkannya setiap kali mengompilasi. Bukti paling cepat: ubah versi kasir-warung menjadi 0.2.0, lalu jalankan cargo build:

cargo build

Output yang Dihasilkan:

   Compiling kasir-warung v0.2.0 (/tmp/w5a/binlib-app)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.14s

Laporan Compiling kasir-warung v0.2.0 membuktikan cargo membaca ulang manifest pada setiap perintah — bukan menyimpannya saat cargo new. Kebiasaan ini penting saat kita bekerja tim: versi di manifest adalah sumber kebenaran tunggal tentang rilis yang sedang dibangun.

Metadata untuk Dunia Luar #

Manifest bawaan cukup untuk build lokal, tetapi kurang untuk package yang akan dibagikan. Cargo mengenali kunci metadata tambahan pada tabel [package] — kita lengkapi manifest kasir-warung:

[package]
name = "kasir-warung"
version = "0.1.0"
edition = "2024"
description = "Alat hitung total belanja untuk warung kecil"
license = "MIT"
authors = ["Budi Santoso <[email protected]>"]

[dependencies]

Bedah ketiga kunci baru tersebut:

1. Baris 5 (description = "Alat hitung total belanja untuk warung kecil"): ringkasan satu kalimat yang ditampilkan di hasil pencarian crates.io dan halaman dokumentasi. Nilainya bebas, tetapi sebaiknya menjelaskan fungsi package secara konkret.
2. Baris 6 (license = "MIT"): jenis lisensi kode. Nilainya memakai identifier standar SPDX seperti MIT, Apache-2.0, atau gabungan "MIT OR Apache-2.0". Kunci ini penting karena tanpa lisensi, orang lain secara hukum tidak diizinkan memakai kode kita.
3. Baris 7 (authors = ["Budi Santoso <[email protected]>"]): daftar penulis dalam format nama dan surel. Nilai boleh berisi lebih dari satu penulis, dipisah sebagai elemen array.

Perintah cargo build sama sekali tidak memedulikan ketiga kunci tersebut — build tetap berhasil dengan atau tanpa metadata. Perhatian muncul belakangan: saat kita membungkus package menjadi arsip untuk dibagikan, cargo memperingatkan manifest yang kekurangan metadata. Kita akan melihat peringatan aslinya pada Chapter Publikasi ke crates.io.

Kunci Lain yang Sering Dipakai #

Selain enam kunci di atas, tabel berikut merangkum kunci [package] yang paling sering dijumpai pada proyek nyata:

Kunci keywords dan categories memudahkan pencarian di registry; kunci readme, repository, dan documentation membantu pemakai memahami proyek sebelum memasangnya. Semuanya opsional untuk build lokal. Menuliskannya sejak awal jauh lebih murah daripada mengejar kelengkapan menjelang publikasi — dan kebiasaan tersebut membuat manifest siap dibagikan kapan pun tanpa persiapan tambahan.

Satu catatan penutup tentang kedudukan manifest: Cargo.toml yang kita bahas di sini berdiri di akar package. Ketika beberapa package hidup bersama dalam satu workspace — struktur yang kita bangun pada Chapter Workspace — tabel profil dan pengaturan bersama justru menempati manifest akar workspace, sedangkan manifest tiap anggota tetap memuat [package] miliknya sendiri. Pemisahan tugas inilah yang menjaga manifest tetap kecil meski proyek membesar.

Edition yang Tidak Dikenal #

Karena edition menentukan aturan bahasa, nilainya tidak bebas — hanya edition yang dikenal cargo yang diterima. Sebagai percobaan, ubah edition = "2024" menjadi edition = "2025" lalu jalankan cargo build:

error: failed to parse manifest at `/tmp/w5a/binlib-app/Cargo.toml`

Caused by:
  failed to parse the `edition` key

Cargo menolak manifest lebih dulu sebelum satu baris Rust pun dikompilasi. Kegagalan seperti ini terjadi pada tahap parse manifest — tahap paling awal dari seluruh alur cargo. Kesalahan ketik pada nilai edition, misalnya edition = "2024 " dengan spasi tersembunyi, menghasilkan kegagalan yang sama. Kembalikan nilainya menjadi "2024", dan build berjalan normal kembali.

Untuk proyek lama yang ingin naik edition, cargo menyediakan pembantu migrasi: perintah cargo fix --edition memindai kode dan menerapkan penyesuaian kecil yang dikenal aman secara otomatis, sebelum kita mengubah nilai edition di manifest. Migrasi tetap perlu diperiksa mata manusia — alat tersebut mengurus pola yang umum, bukan seluruh perubahan makna.

Ringkasan #

Cargo.toml adalah manifest yang dibaca cargo pada setiap perintah: tabel [package] memuat identitas (name, version, edition) beserta metadata publikasi (description, license, authors, dan kunci opsional lain), sedangkan tabel [dependencies] menampung daftar crate eksternal yang masih kosong. Nilai version terbukti ikut tercetak pada laporan build, dan nilai edition yang tidak dikenal membuat manifest ditolak sebelum kompilasi dimulai. Tabel [dependencies] yang selama ini kosong itulah yang kita isi pertama kali pada Chapter berikutnya — dengan crate nyata dari registry crates.io.