Package Zero: Penjelasan zero.json, src/, dan Target

Kenapa Perlu Package

Satu file .0 sudah cukup saat kamu sedang belajar bahasanya atau mencoba potongan kode. Begitu proyekmu lebih dari satu file, kamu butuh package, yaitu folder dengan manifest dan susunan yang sudah dikenal oleh toolchain.

Keuntungan berpindah dari file-file lepas ke package:

• Satu tempat resmi untuk nama, versi, dan metadata proyek.
• Beberapa titik masuk (executable, library, test) dalam satu struktur folder.
• Susunan yang mudah ditebak: tool bisa menemukan kode sumbermu tanpa konfigurasi.
• zero check / zero build untuk seluruh proyek sekaligus, bukan file demi file.

Membuat Kerangka Package

Cara tercepat untuk memulai adalah zero new:

zero new cli hello

Perintah itu membuat folder hello/ dengan susunan seperti ini:

hello/
├── zero.json
└── src/
    └── main.0

cli adalah nama template, yang menghasilkan program command line yang bisa dieksekusi. Template lain (library, program sistem) memakai bentuk yang sama dengan default yang berbeda.

Masuk ke folder baru dengan cd, jalankan, dan kamu siap mulai:

cd hello
zero run

Saat kamu memanggil zero run dari dalam folder package tanpa menyebut nama file, perintah itu mengambil target default dari zero.json lalu menjalankannya.

Manifest zero.json

Manifest dari package cli yang baru dibuat terlihat seperti ini:

{
    "package": { "name": "hello", "version": "0.1.0" },
    "targets": { "cli": { "kind": "exe", "main": "src/main.0" } }
}

Ada dua key di tingkat atas: package dan targets. Yang pertama mengidentifikasi package, yang kedua memberi tahu compiler apa yang harus dibangun.

package

"package": {
    "name": "hello",
    "version": "0.1.0"
}

• name: slug yang mengidentifikasi package. Pakai huruf kecil dan tanda hubung.
• version: string semver. Package yang masih di bawah 1.0 memakai 0.x.y.

Field metadata lain (deskripsi, penulis, lisensi, repository) mungkin didukung. Ikuti dokumentasi Zero terbaru untuk skema resminya, karena manifest ini masih terus berkembang.

targets

"targets": {
    "cli": { "kind": "exe", "main": "src/main.0" }
}

Key-nya (di sini cli) adalah nama target yang kamu pilih sendiri. Nilainya menjelaskan setiap target:

• kind: jenis target. exe untuk executable. Jenis lain (library, test) memakai bentuk yang sama.
• main: file sumber titik masuk, relatif terhadap root package.

Kamu bisa mendeklarasikan lebih dari satu target dalam package yang sama:

{
    "package": { "name": "image-tools", "version": "0.1.0" },
    "targets": {
        "convert": { "kind": "exe", "main": "src/convert.0" },
        "resize":  { "kind": "exe", "main": "src/resize.0" },
        "lib":     { "kind": "lib", "main": "src/lib.0" }
    }
}

Bangun target tertentu dengan CLI dengan menyebut namanya:

zero build convert
zero run resize

Folder src/

Semua file sumber berada di dalam src/. Compiler menelusuri folder ini secara otomatis, jadi kamu tidak perlu mencantumkan setiap file di manifest. Field main setiap target menunjuk ke file titik masuknya, dan dari sana compiler mengikuti import untuk menemukan semua yang dibutuhkan.

Package dengan beberapa module bantuan bisa terlihat seperti ini:

image-tools/
├── zero.json
└── src/
    ├── convert.0
    ├── resize.0
    ├── lib.0
    └── internal/
        ├── decoder.0
        └── encoder.0

Subfolder internal/ hanyalah konvensi. Tidak ada bagian manifest yang menyebut file-file itu. Import di dalam convert.0 langsung menjangkau internal/decoder.0.

Build dan Menjalankan Program

Alur kerja yang umum saat kamu berada di dalam package:

zero check        # type-check the whole tree
zero run          # build and run the default target
zero run convert  # build and run a specific named target
zero build        # build the default target
zero build --all  # build every target (when supported)
zero test         # run every test target

CLI membaca zero.json, menentukan apa yang harus dilakukan, lalu menjalankannya. Saat bekerja di dalam package, kamu jarang perlu menulis path secara lengkap.

Beberapa File Sumber: Contoh Singkat

Misalkan src/main.0 memanggil fungsi bantuan dari src/math.0. Ini file bantuannya:

pub fun double(value: i32) -> i32 {
    return value * 2
}

Ini file titik masuknya:

pub fun main(world: World) -> Void raises {
    let result = double(21)
    if result == 42 {
        check world.out.write("forty two\n")
    }
}

Jalankan dengan zero run. Dalam kasus sederhana ini, compiler mencari referensi ke double di seluruh kode sumber tanpa deklarasi import yang eksplisit. Saat package makin besar, sistem import eksplisit menangani visibilitas antar-module. Lihat dokumentasi Zero terbaru untuk sintaks import, karena bagian inilah yang paling mungkin berubah sebelum 1.0.

Yang Tidak Perlu Dimasukkan ke Git

File .gitignore untuk package Zero biasanya berisi:

# build artifacts and caches
/build/
/target/

# editor cruft
.DS_Store
*.swp

Nama folder hasil build bisa saja berbeda (cek dokumentasi toolchain terbaru), tetapi aturannya tetap: kode sumber masuk ke git, hasil build tidak.

Berbagi Package

Zero masih di bawah 1.0, dan registry package belum menjadi bagian yang stabil. Untuk sekarang, cara praktis untuk berbagi package adalah:

• Git: clone repo-nya lalu jalankan zero check di sana.
• Salinan vendor: taruh salinan kode sumbernya di proyek lain.

Saat registry tersedia, referensi package kemungkinan akan dipindahkan ke field dependencies di zero.json. Anggap itu fitur masa depan, bukan sesuatu yang bisa kamu andalkan di script hari ini.

Berikutnya: Dasar Bahasa

Sekarang kamu sudah punya semua yang dibutuhkan untuk menyusun proyek Zero sungguhan. Bab berikutnya membahas bahasanya sendiri secara lebih dekat, dimulai dari binding let, yaitu cara nilai di Zero diberi nama.