Package dan Library

Topik ini membahas tiga satuan organisasi kode dalam Carbon, yaitu package sebagai wadah berkas, library sebagai satuan penggunaan ulang, dan import sebagai akses lintas library. Pembahasan dimulai dari peran setiap satuan, dilanjutkan dengan aturan deklarasinya, lalu ditutup dengan program kecil yang dijalankan di Compiler Explorer. Setelah membaca topik ini, struktur deklarasi di bagian atas sebuah berkas Carbon dapat dibaca dan maksud tiap deklarasi dapat dijelaskan.

Package sebagai wadah berkas#

Package adalah satuan distribusi kode dalam Carbon, dan setiap berkas Carbon menyatakan keanggotaannya melalui deklarasi package pada baris pertama. Dokumen desain resmi menyebut berkas sebagai satuan kompilasi paling dasar yang berekstensi .carbon, kemudian berkas-berkas itu dikelompokkan menjadi library, dan library dikelompokkan menjadi package. Nama package sekaligus berfungsi sebagai ruang nama (namespace) paling luar, sehingga dua package yang berbeda dapat memakai nama yang sama tanpa saling bertabrakan. Nama package ditulis sebagai satu pengenal tunggal, misalnya Konversi atau Suhu, dan glosarium resmi menganjurkan nama yang unik secara global.

Deklarasi package pada berkas paling sederhana terlihat seperti berikut.

// tidak-dijalankan
package Konversi api;

Berkas di atas menyatakan diri sebagai bagian dari package Konversi dan berperan sebagai berkas api, yaitu berkas yang memuat antarmuka. Kata api dan impl pada deklarasi menandai dua jenis berkas dalam satu library, dan pembahasan lengkapnya ada pada topik berkas api dan impl. Ada satu kasus khusus yang perlu diketahui sejak awal, yaitu berkas tanpa deklarasi package sama sekali. Menurut dokumen desain, berkas semacam itu masuk ke package Main, yaitu package tempat titik masuk program berada, dan package Main tidak dapat diimpor dari package lain.

Library sebagai satuan penggunaan ulang#

Library adalah grup berkas yang membentuk satu kesatuan kode yang dapat diimpor, dan menjadi satuan penggunaan ulang paling kecil dalam Carbon. Setiap library wajib memiliki tepat satu berkas api yang memuat deklarasi seluruh nama publik, sedangkan definisinya boleh berada di berkas api itu sendiri atau di berkas impl. Library diberi nama melalui klausa library pada deklarasi package, misalnya package Geometry library "Shapes"; sebagaimana ditulis dokumen desain, sedangkan library tanpa klausa nama disebut library default. Diagram berikut memperlihatkan kedudukan package, library, dan berkas dalam satu hierarki.

Dokumen desain memberi dua peran berbeda pada dua satuan ini, yaitu package sebagai satuan distribusi dan library sebagai satuan ketergantungan. Pembedaan tersebut berdampak nyata pada proses build, karena perubahan pada berkas impl satu library tidak memicu kompilasi ulang pada library lain yang hanya membaca api-nya. Dokumen desain juga menganjurkan library berukuran kecil yang dikumpulkan dalam package lebih besar, sehingga satuan penggunaan ulang tetap ramping dan mudah dipindahkan antarproyek.

Import sebagai akses lintas library#

Import adalah pernyataan yang membuka nama-nama publik dari sebuah library agar dapat digunakan di berkas lain. Pernyataan import ditulis setelah deklarasi package dan wajib berada sebelum semua deklarasi lain di berkas. Untuk library di dalam package yang sama, nama package ditiadakan, sedangkan untuk library milik package lain, nama package disebut lebih dulu.

// tidak-dijalankan
import library "Suhu";

// tidak-dijalankan
import Konversi;

// tidak-dijalankan
import Konversi library "Suhu";

Nama yang dihasilkan import dapat diakses sebagai anggota. Menurut dokumen desain, import Math; membuka library default package Math, sehingga fungsi akar kuadrat dipanggil sebagai Math.Sqrt, dan pola yang sama berlaku untuk package lain seperti Konversi.CKeF pada contoh di bagian akhir. Bentuk import library "Suhu"; bekerja sedikit berbeda, yaitu menambahkan semua nama publik library itu langsung ke lingkup atas berkas sebagai nama privat. Mekanisme ini lebih menyerupai module C++ daripada #include, karena yang diimpor adalah library sebagai kesatuan yang sudah diperiksa, bukan penyisipan teks dari praprosesor. Karena setiap package memiliki ruang nama sendiri, dua library dari package berbeda tidak akan bentrok nama, dan library di dalam satu package hanya perlu berkoordinasi dengan sesamanya.

Membaca struktur program lewat contoh nyata#

Struktur package, library, dan berkas menjadi lebih konkret apabila diamati pada program yang benar-benar dijalankan. Program berikut berada dalam satu berkas bernama konversi.carbon, dan berkas itu menyatakan diri sebagai berkas api dari package Konversi. Dua fungsi konversi suhu dideklarasikan pada lingkup package, kemudian fungsi Main memanggil keduanya dan mencetak hasilnya.

package Konversi api;

fn CKeF(celsius: i32) -> i32 {
  return celsius * 9 / 5 + 32;
}

fn CKeK(celsius: i32) -> i32 {
  return celsius + 273;
}

fn Main() -> i32 {
  Print("100 C = {0} F", CKeF(100));
  Print("100 C = {0} K", CKeK(100));
  return 0;
}

100 C = 212 F
100 C = 373 K
result: 0

Program ini dieksekusi melalui Carbon Explorer pada Compiler Explorer, dan keluarannya tampil persis seperti di atas. Dua baris pertama berasal dari dua pernyataan Print, sedangkan baris result: 0 adalah kode kembalian fungsi Main yang selalu ditambahkan Explorer di akhir. Kata kunci fn dan fungsi Main dibahas tuntas pada topik fn dan Hello World, sehingga pada tahap ini cukup diamati bentuk deklarasinya. Perhatikan pula bahwa nama Konversi bukan nama yang diwajibkan alat, melainkan pilihan bebas, karena Explorer mengeksekusi berkas yang aktif sebagai program utuh.

Pengorganisasian kode ke dalam package dan library memang terasa berlebihan untuk program satu berkas, tetapi desain ini menyiapkan proyek yang terus tumbuh. Apabila suatu saat konversi suhu, panjang, dan mata uang dipisah menjadi tiga library, bagian lain dari program cukup mengimpor api-nya tanpa mengetahui detail implementasinya. Prinsip inilah yang mendasari penyebutan package sebagai satuan distribusi dan library sebagai satuan penggunaan ulang.

Ringkasan#

• Setiap berkas Carbon diawali deklarasi package, misalnya package Konversi api;, dan nama package sekaligus menjadi ruang nama paling luar bagi seluruh isinya.
• Library adalah grup berkas dengan tepat satu berkas api dan nol atau lebih berkas impl, serta menjadi satuan yang diimpor dan satuan ketergantungan dalam build.
• Pernyataan import membuka nama publik library lain, dengan akses anggota melalui nama package seperti Math.Sqrt.
• Berkas tanpa deklarasi package masuk ke package Main yang tidak dapat diimpor dari luar.

Referensi#

• Design README — Carbon Language — Bagian Files, libraries, packages serta Imports menetapkan peran package, library, api, impl, dan import.
• Code and name organization — Carbon Language — Dokumen desain organisasi kode yang menjelaskan package sebagai satuan distribusi dan library sebagai satuan ketergantungan.
• Glossary — Carbon Language — Definisi resmi istilah package dan library beserta anjuran penamaannya.
• Compiler Explorer — Godbolt Compiler Explorer — Layanan tempat seluruh program Carbon pada topik ini dieksekusi.