KAL
Menu

Rilis

Memublikasikan paket, membangun biner rilis, dan menyempurnakan README.

Daftar isi

Proyek yang berfungsi pada direktori kerja belum tentu siap dipakai orang lain. Topik ini menutup proyek suhu dengan tiga pekerjaan rilis, yaitu membungkusnya sebagai paket nimble, membangun biner rilis yang dioptimasi, dan menyempurnakan README sehingga pengguna baru dapat menjalankannya sendiri. Seluruh berkas sumber proyek dibawa tanpa perubahan dari tahap pembangunan, sehingga fokus di sini sepenuhnya pada pengemasan dan publikasi.

Berkas paket nimble#

Paket nimble didefinisikan oleh satu berkas yang namanya harus sama dengan nama paket, yaitu suhu.nimble untuk paket bernama suhu. Berkas ini menetapkan identitas paket, dependensinya, biner yang dihasilkan, serta tugas tambahan seperti pengujian:

nim suhu.nimble 
# Package

version       = "0.1.0"
author        = "Budi"
description   = "Alat CLI statistik catatan suhu berformat CSV"
license       = "MIT"

# Dependencies

requires "nim >= 2.4.0"

# Build

bin           = @["suhu"]

# Tugas

task test, "menjalankan seluruh pengujian":
  selfExec "c -r --hints:off tes_parser"
  selfExec "c -r --hints:off tes_statistik"

Kunci bin menyatakan biner yang dibangun nimble, sedangkan requires menyatakan syarat versi, dan dalam kasus ini cukup Nim 2.4.0 karena proyeknya tidak memakai paket pihak ketiga. Tugas test memanggil selfExec, yaitu perintah yang menjalankan compiler dengan konfigurasi nimble, sehingga pengguna paket tidak perlu tahu nama-nama berkas tesnya. Nama berkas paket wajib sama dengan nama paketnya karena nimble mengenali paket dari berkas .nimble yang ditemuinya, bukan dari kunci di dalamnya. Nimble sendiri adalah pengelola paket resmi ekosistem Nim, yaitu alat yang memasang paket dari daftar resmi beserta dependensinya, dan nomor versi paket dinyatakan hanya di berkas ini. Struktur lengkap direktori proyek pada tahap ini adalah sebagai berikut:

text 
suhu/
├── README.md
├── suhu.nimble
├── suhu.nim
├── parser.nim
├── statistik.nim
├── tes_parser.nim
├── tes_statistik.nim
└── suhu.csv

Pembangunan dan pengujian lewat nimble#

Dengan berkas paket tersedia, pembangunan dan pengujian berpindah ke nimble. Perintah nimble build membaca suhu.nimble, memeriksa dependensi, lalu mengompilasi seluruh entri pada kunci bin dengan konfigurasi nimble, dan biner yang dihasilkan bernama sama dengan entrinya, yaitu suhu:

bash 
# membangun paket lewat nimble
nimble build
text Keluaran 
      Info: using /home/kal/my-project/tools/nim-2.4.0/bin/nim for compilation
   Building suhu/suhu using c backend

Baris Info pada keluaran menunjukkan compiler yang dipakai nimble, sehingga perbedaan versi antar lingkungan mudah dideteksi. Pengembang tetap bebas memanggil nim c secara langsung selama pengembangan harian, sedangkan nimble menjadi lapisan yang seragam bagi pengguna paket. Kombinasi keduanya, yaitu nimble untuk pengguna dan nim c untuk pengembang, lazim pada proyek Nim kecil maupun besar, dan keduanya memakai berkas sumber yang sama tanpa penyetelan ulang.

Perintah nimble test menjalankan tugas test yang barusan didefinisikan, sehingga dua berkas tes dijalankan berurutan dalam satu perintah:

bash 
# menjalankan seluruh tes lewat tugas paket
nimble test
text Keluaran 
      Info: using /home/kal/my-project/tools/nim-2.4.0/bin/nim for compilation
  Executing task test in /home/kal/my-project/content/nim/pengerjaan-proyek/rilis/suhu.nimble

[Suite] urai baris
  [OK] baris lengkap
  [OK] spasi sebelum angka diabaikan
  [OK] kolom suhu bukan angka memunculkan ValueError

[Suite] urai csv
  [OK] header dan baris kosong dilewati
  [OK] kolom kurang dari dua memunculkan ValueError

[Suite] statistik deret
  [OK] minimum dan maksimum
  [OK] rata-rata tiga nilai
  [OK] median dengan banyak data ganjil
  [OK] median dengan banyak data genap

Sembilan tes pada tiga suite semuanya lulus, dan keluaran tersebut menjadi bukti rilis yang dapat disertakan pada pengumuman versi. Sejak titik ini, pengguna paket tidak perlu mengetahui detail kompilasi, cukup nimble build dan nimble test.

Biner rilis#

Biner bawaan hasil nim c belum dioptimasi, sehingga biner yang dibagikan dibangun ulang dengan dua sakelar, yaitu -d:release yang mengaktifkan optimasi dan menonaktifkan pemeriksaan runtime yang mahal, serta --opt:speed yang menyetel optimasinya ke kecepatan:

bash 
# membangun biner rilis dengan optimasi
nim c -d:release --opt:speed --hints:off -o:suhu-rilis suhu.nim
# memeriksa status simbol dan ukuran berkas
file suhu-rilis | grep -o "not stripped"
wc -c < suhu-rilis
text Keluaran 
not stripped
109104

Hasilnya berukuran 109.104 byte dan masih membawa simbol debug, yaitu tabel nama fungsi dan variabel yang dipakai alat debugger. Simbol tersebut tidak diperlukan pada biner yang dibagikan, sehingga dilepas dengan strip:

bash 
# membuang simbol debug dari biner rilis
strip suhu-rilis
# memeriksa ulang status simbol dan ukurannya
file suhu-rilis | grep -o "stripped"
wc -c < suhu-rilis
text Keluaran 
stripped
93080

Pembuangan simbol mengecilkan biner menjadi 93.080 byte tanpa mengubah perilakunya, dan file kini melaporkannya sebagai stripped. Sakelar -d:release sendiri mengubah perilaku program, yaitu banyak pemeriksaan runtime yang mahal dinonaktifkan dan optimizer compiler diaktifkan, sehingga hasilnya lebih cepat. Karena perbedaan perilaku itulah biner rilis selalu diuji ulang setelah dibangun, seperti dilakukan di bawah, dan tidak sekadar disalin dari biner pengembangan. Pada lingkungan yang sama, pembangunan ulang dengan compiler serta sakelar yang sama menghasilkan biner yang identik, sebuah sifat yang memudahkan penelusuran bug pada versi tertentu. Biner rilis diuji sekali lagi untuk memastikan laporannya tetap benar setelah optimasi:

bash 
# menguji biner rilis dengan berkas data
./suhu-rilis suhu.csv
text Keluaran 
Berkas       : suhu.csv
Banyak data  : 10
Suhu minimum : 20.50
Suhu maksimum: 24.00
Rata-rata    : 22.22
Median       : 22.20

README yang lengkap#

README adalah muka paket, dan isi yang baik menjawab empat pertanyaan pengguna baru dalam satu tarikan napas, yaitu program ini apa, cara memakainya, keluarannya seperti apa, dan cara membangunnya. Berkas README.md proyek suhu berikut mengikuti pola tersebut, dan setiap keluaran di dalamnya disalin dari eksekusi nyata:

markdown README.md 
# suhu

Alat baris perintah untuk menghitung statistik deskriptif dari berkas CSV
catatan suhu. Program ini ditulis dalam Nim tanpa dependensi eksternal.

## Pemakaian

```text
suhu <berkas.csv>
```

Berkas CSV harus memiliki baris header `tanggal,suhu` dan satu catatan
per baris.

## Contoh

Dengan berkas `suhu.csv` berisi sepuluh catatan harian:

```text
Berkas       : suhu.csv
Banyak data  : 10
Suhu minimum : 20.50
Suhu maksimum: 24.00
Rata-rata    : 22.22
Median       : 22.20
```

## Membangun

```bash
nim c -d:release --opt:speed suhu.nim
```

## Pengujian

```bash
nimble test
```

## Struktur

- `suhu.nim` : titik masuk program dan penyusunan laporan
- `parser.nim` : penguraian berkas CSV
- `statistik.nim` : perhitungan statistik deskriptif

## Lisensi

MIT

Bagian contoh adalah yang paling sering diabaikan, padahal keluaran nyata memberi pembaca patokan yang bisa dibandingkan dengan sistemnya sendiri. Urutan bagiannya juga disengaja, yaitu pemakaian lebih dahulu, contoh keluaran berikutnya, lalu petunjuk membangun, karena itulah urutan pertanyaan yang alami dari pengguna baru. Nama proyek pada judulnya disamakan dengan nama paket nimble agar pencarian antar keduanya konsisten. Lisensi juga dicantumkan eksplisit karena paket tanpa lisensi tidak dapat dipakai aman oleh pihak lain, dan MIT pada proyek ini dipilih karena bentuknya pendek serta mengizinkan pemakaian luas.

Mempublikasikan paket#

Publikasi membuat paket dapat dipasang oleh siapa pun dengan satu perintah nimble install suhu. Cara resminya adalah mengunggah proyek ke repository publik, lalu mendaftarkannya pada daftar paket resmi nimble, yang dikelola pada repository nim-lang/packages berisi berkas packages.json. Langkah-langkahnya memerlukan repository remote dan akun hosting Git, sehingga tidak dapat dieksekusi penuh di lingkungan sandbox ini:

bash 
# tidak-dijalankan: butuh repository remote dan akun hosting Git
# menginisialisasi repository proyek dan merekam seluruh berkas sumber
git init
git add README.md suhu.nimble suhu.nim parser.nim statistik.nim tes_parser.nim tes_statistik.nim
git commit -m "Rilis suhu 0.1.0"
# menandai versi agar sama dengan versi pada suhu.nimble
git tag v0.1.0
# mengunggah ke repository publik, misalnya GitHub
git push origin main --tags

Setelah repositorynya publik, paket didaftarkan dengan menambahkan satu entri ke packages.json melalui pull request, berisi nama, url repository, deskripsi, dan daftar tag. Daftar resmi itu disimpan sebagai satu berkas JSON yang disunting melalui pull request, sehingga setiap paket baru melewati pemeriksaan manusia sebelum terdaftar. Ketika pull request itu digabungkan, nimble install suhu sudah berfungsi bagi semua pengguna nimble, dan pembaruan versi berikutnya cukup dengan menaikkan kunci version, membuat tag baru, lalu memperbarui entri paketnya.

Kesalahan umum#

  • Membagikan biner tanpa -d:release. Biner pengembangan bekerja dengan benar, tetapi performanya tertinggal jauh dari biner rilis. Perbaikannya adalah membangun ulang dengan -d:release --opt:speed, lalu mengujinya sekali lagi sebelum dibagikan.
  • README tanpa contoh keluaran. Penjelasan yang hanya berisi daftar fitur tidak memberi patokan apa pun kepada pengguna baru. Perbaikannya adalah menyertakan keluaran asli pada contoh, persis seperti bagian contoh README di atas.
  • Versi nimble dan tag Git yang tidak sinkron. Pengguna yang menelusuri bug pada versi tertentu akan salah membaca riwayat kode. Perbaikannya adalah menaikkan kunci version dan membuat tag dalam satu langkah kerja yang sama.
  • Membagikan isi berbeda dengan nomor versi sama. Pengguna yang sudah memasang versi lama tidak dapat membedakannya dari versi baru yang belum diberi nomor naik. Perbaikannya adalah menaikkan nomor versi pada setiap perubahan yang dibagikan, sekecil apa pun perubahannya, dan menyesuaikan tag Git-nya sekaligus.

Ringkasan#

  • Paket nimble didefinisikan pada suhu.nimble yang memuat identitas, dependensi, kunci bin, dan tugas test yang menjalankan dua berkas tes.
  • nimble build dan nimble test menjadi antarmuka baku pembangunan dan pengujian bagi pengguna paket.
  • Biner rilis dibangun dengan -d:release --opt:speed lalu dihapus simbolnya dengan strip, memperkecil ukurannya dari 109.104 menjadi 93.080 byte tanpa mengubah perilaku.
  • Publikasi resmi mengunggah repository beserta tag versi, lalu mendaftarkan paket pada packages.json di repository nim-lang/packages melalui pull request.

Referensi#